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

平台概览

智行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 文档检索样本文本"
  }'

Codex / ClaudeCode

命令行工具建议先在 Linux、macOS 或 WSL 环境安装 Node.js 22+ 和 npm 10+。令牌只写在本机用户目录或环境变量里，不要写入项目仓库。

Codex

安装 Codex 后，配置 ~/.codex/auth.json 与 ~/.codex/config.toml。这里使用 Responses wire API，适合 Codex 新版模型调用。

npm install -g @openai/codex

{
  "OPENAI_API_KEY": "sk-你的令牌"
}

model_provider = "zhixing"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.zhixing]
name = "zhixing"
base_url = "https://zhixingai.cloud/v1"
wire_api = "responses"

ClaudeCode

ClaudeCode 使用 Anthropic 兼容环境变量。这里的 base URL 填根域名，让客户端自行拼接 /v1/messages。

npm install -g @anthropic-ai/claude-code

export ANTHROPIC_BASE_URL="https://zhixingai.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-你的令牌"
claude

set ANTHROPIC_BASE_URL=https://zhixingai.cloud
set ANTHROPIC_AUTH_TOKEN=sk-你的令牌
claude

Dify / Cherry Studio

Dify、Cherry Studio、Coze、N8N 等工具本质上都是填写兼容供应商、API 地址、令牌和模型名。不同产品的字段命名不同，但映射关系一致。

扩展接口

下面这些接口与基础聊天接口同域名共存。OpenAI 兼容能力通常走 /v1，Gemini 走 /v1beta，MJ 与 Suno 直接从根域名调用对应路径。

图片生成

curl https://zhixingai.cloud/v1/images/generations \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张简洁的智行API 开发者控制台产品图，深色背景，清晰可读",
    "size": "1024x1024",
    "n": 1
  }'

视频任务

视频生成通常是异步任务：先提交任务拿到 id，再用查询接口轮询状态。Veo、Seedance、Wanxiang、Grok、Sora 等模型可以共用或兼容 /v1/videos 任务格式。

curl https://zhixingai.cloud/v1/videos \
  -H "Authorization: Bearer sk-你的令牌" \
  -F "model=seedance-2.0" \
  -F "prompt=城市广场中央的机器人正在跳舞，电影感镜头，细节清晰" \
  -F "size=1280x720" \
  -F "seconds=8"

curl https://zhixingai.cloud/v1/videos/video_task_id \
  -H "Authorization: Bearer sk-你的令牌"

Midjourney

Midjourney 接口使用独立的 /mj 路径。提交类接口返回任务 ID，后续通过查询接口获取进度、图片地址和最终状态。

curl https://zhixingai.cloud/mj/submit/imagine \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "botType": "MID_JOURNEY",
    "prompt": "developer documentation homepage for Zhixing API, clean product screenshot style",
    "base64Array": [],
    "notifyHook": "",
    "state": "zhixing-doc-demo"
  }'

curl https://zhixingai.cloud/mj/task/mj_task_id/fetch \
  -H "Authorization: Bearer sk-你的令牌"

Suno 音乐

Suno 接口使用 /suno 路径，生成音乐、歌词、续写、拼接和格式转换都按任务处理。提交后保存任务 ID，用批量或单个查询接口获取结果。

curl https://zhixingai.cloud/suno/submit/music \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一首适合开发者产品发布会的中文电子流行歌曲",
    "title": "智行接口",
    "tags": "electropop, clean vocal, upbeat",
    "mv": "chirp-v4",
    "make_instrumental": false
  }'

curl https://zhixingai.cloud/suno/fetch \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["suno_task_id"]
  }'

用户查询

用户接口用于查询令牌日志、订阅信息和已使用额度。后台如果限制了这些接口，业务侧应以控制台和管理端权限为准。

curl "https://zhixingai.cloud/api/log/token?key=sk-你的令牌"

curl https://zhixingai.cloud/v1/dashboard/billing/usage \
  -H "Authorization: Bearer sk-你的令牌"

模型与分组

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

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

额度与计费

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

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

错误码

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

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

接入兼容

所有内容已经合并在同一页，业务接入只需要按协议选择正确 base URL。实际落地时按下面顺序排查即可。

1. OpenAI SDK 只填 https://zhixingai.cloud/v1，请求路径不要再手写一个 /v1。
2. ClaudeCode 环境变量填 https://zhixingai.cloud，让工具自己拼接 Anthropic 路径。
3. Gemini 客户端如果自动拼 /v1beta，base URL 填根域名；如果不自动拼，填 https://zhixingai.cloud/v1beta。
4. MJ、Suno、用户日志接口不属于 OpenAI SDK 路径，直接从根域名调用 /mj/*、/suno/*、/api/*。
5. 图片、视频和音频模型字段差异较大，优先用控制台当前模型说明和最小请求测试。

最佳实践

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