一套密钥，调用多家模型。

平台概览

智行API 提供统一的模型访问入口，把不同供应商、不同格式、不同渠道分组封装成稳定的 HTTP API。业务侧只需要管理自己的 API Key、模型名、调用参数和错误重试策略。

快速开始

在控制台创建令牌后，将 SDK 的服务地址改为 https://zhixingai.cloud/v1。下面示例使用 OpenAI 官方 SDK 的兼容调用方式。

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHIXING_API_KEY,
  baseURL: "https://zhixingai.cloud/v1"
});

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "你是一个简洁的技术助手。" },
    { role: "user", content: "用一句话介绍智行API。" }
  ]
});

console.log(completion.choices[0].message.content);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://zhixingai.cloud/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "返回一个 JSON 格式的接入检查清单"}
    ],
)

print(resp.choices[0].message.content)

cURL

curl https://zhixingai.cloud/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "测试连接是否正常"}
    ]
  }'

认证与令牌

所有模型调用都通过 Bearer Token 鉴权。令牌在控制台创建，可以限制额度、过期时间、模型访问范围、IP 白名单和可用分组。

服务端调用建议把令牌放在环境变量中，例如 ZHIXING_API_KEY。多租户系统建议为不同用户或业务线分配独立令牌，方便额度、风控和审计。

接口总览

以下路径均以 https://zhixingai.cloud 为根域名。OpenAI 兼容接口通常以 /v1 开头。

Chat Completions

这是最常用的兼容接口，适合绝大多数聊天、分类、抽取、改写、代码生成和客服场景。

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "你只输出 JSON。"},
    {"role": "user", "content": "提取订单号：订单 ZX-20260508 已支付"}
  ],
  "temperature": 0.2,
  "stream": false
}

流式输出

把 stream 设为 true 后，服务会按 SSE 分片返回增量内容。前端或后端需要按 data: 行解析，直到收到 [DONE]。

curl https://zhixingai.cloud/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [{"role":"user","content":"分三点介绍流式输出"}]
  }'

Responses API

/v1/responses 适合需要统一输入输出结构的新式任务。不同上游模型的支持能力会有差异，生产环境建议在上线前对目标模型做固定用例回归。

const response = await client.responses.create({
  model: "gpt-5-mini",
  input: [
    {
      role: "user",
      content: "写一个用于健康检查的 JSON 响应示例"
    }
  ]
});

console.log(response.output_text);

如果你的 SDK 还不支持 Responses API，可以用普通 HTTP POST 调用。

Claude 兼容

Claude Messages 兼容入口为 /v1/messages。当你使用 Claude SDK 或 Anthropic 兼容客户端时，把 base URL 指到智行API 域名，并使用智行API 令牌。

curl https://zhixingai.cloud/v1/messages \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "给出 API 网关的三条稳定性建议"}
    ]
  }'

Gemini 兼容

Gemini 兼容接口通常使用 /v1beta 路径。不同 SDK 对 base URL 拼接规则不同，建议先用 cURL 完成联调，再接入业务 SDK。

curl "https://zhixingai.cloud/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "用一句话解释模型聚合网关"}
        ]
      }
    ]
  }'

图像、嵌入与音频

智行API 支持多种非聊天能力。实际可用模型由后台渠道和用户分组决定。

curl https://zhixingai.cloud/v1/embeddings \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "智行API 文档检索样本文本"
  }'

模型与分组

智行API 使用“模型 + 分组 + 渠道”的方式路由请求。管理员可以把不同供应商、不同价格、不同稳定性的渠道放入不同分组，用户令牌只会访问被授权的分组。

如果某个模型返回不可用，通常需要检查三件事：模型名是否存在、令牌是否允许该模型、令牌所属分组是否有可用渠道。

额度与计费

额度消耗由模型倍率、分组倍率、输入输出 token、图片或音频等附加计费项共同决定。不同模型的实际成本差异很大，生产环境建议按业务线创建独立令牌，并设置额度上限。

• 聊天与文本模型通常按输入 token 和输出 token 计费。
• 图片、音频、缓存读写、重排等能力可能有独立倍率。
• 流式输出不改变最终计费逻辑，只改变响应传输方式。
• 重试会产生额外消耗，客户端应限制最大重试次数。

错误码

智行API 尽量保持与 OpenAI 兼容的错误返回格式。客户端应同时读取 HTTP 状态码和响应体里的错误信息。

{
  "error": {
    "message": "令牌无效或额度不足",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

最佳实践

1. 服务端保存 API Key，不要在浏览器、移动端或公开配置里暴露真实令牌。
2. 为开发、测试、生产分别创建令牌，生产令牌设置额度上限和 IP 限制。
3. 对 429、502、503 使用指数退避重试，对非幂等任务不要盲目重放。
4. 记录模型名、分组、请求 ID、耗时、状态码和错误摘要，便于定位渠道问题。
5. 固定生产模型名，不要依赖随时变化的 latest 模型做关键业务决策。
6. 上线前为结构化输出、工具调用、长上下文和多模态输入分别做回归用例。