API 调用指南

1. Base URL 与鉴权

将下面示例中的 https://api.example.com 替换为你的平台入口地址。生产部署应通过 HTTPS 访问，由 nginx 反向代理到数据服务 :8001。

2. 获取模型列表

curl https://api.example.com/v1/models

返回 OpenAI 格式的可用模型。每个模型由平台的路由映射到一个或多个渠道账号。id 是请求时传入的模型名。

{
  "object": "list",
  "data": [
    { "id": "gpt-4o", "object": "model", "created": 1700000000, "owned_by": "..." }
  ]
}

3. Chat Completions（OpenAI 兼容）

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "用一句话介绍模型代理平台"}],
    "stream": false
  }'

3.1 流式

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "讲一个技术笑话"}],
    "stream": true
  }'

响应是 SSE，每条以 data: 开头，最后以 data: [DONE] 结束。平台会过滤上游心跳/注释事件；若上游在未完整结束前断开且开启了流式完整性策略，会返回流式错误而非伪造成正常结束，便于客户端重试。

3.2 工具调用

支持原生 tools 的渠道直接转发；对不支持原生工具调用的渠道，平台可注入工具提示词并解析模型输出为工具调用。请求格式与 OpenAI 一致，无需特殊适配。

4. Anthropic Messages 兼容

curl https://api.example.com/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话介绍 Agent 节点系统"}]
  }'

• 同时支持 /v1/messages 与无前缀的 /messages。
• 错误返回 Anthropic 格式：{"type":"error","error":{"type":"...","message":"..."}}。
• 同协议直通：当上游渠道本身就是 Anthropic 协议、且流式与非流式形态一致时，平台原样转发上游 SSE/JSON，保留 signature、cache_control、content block 顺序、citations 等全部字段，不做重写。
• 连接复用：平台复用出站连接池，避免每次请求重复建立 TCP/TLS 连接，减少握手等待，让高频 LLM 请求更快返回。
• 只有跨协议路径（例如客户端发 Anthropic、上游是 OpenAI）才做字段映射：thinking 与 reasoning_content 双向转换、工具调用与 finish_reason 映射。
• 关闭思考一律通过省略参数表达，不会向上游注入 reasoning_effort: none 之类的非标准值污染请求。

5. OpenAI Responses 兼容

curl https://api.example.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "总结一下多渠道代理的核心价值"
  }'

同时支持 /v1/responses 与 /responses。可用于偏好 Responses API 风格的客户端和 SDK。

6. 编码类客户端接入

Claude Code、Codex CLI、Cursor、Cline、Roo Code、opencode 等编码工具通常只需把 base URL 与 API Key 指向平台即可使用，不需要改造。平台在渠道侧提供客户端模板能力：当上游要求特定客户端形态时，管理员为该渠道配置对应模板，平台会按目标协议构造请求，并补齐上游期望的请求头与默认字段。

平台还会识别客户端类型（请求头特征、body 中的 client_type、或 system 提示词特征），据此应用对应的默认字段。你显式传入的标准参数始终优先——例如已带 reasoning_effort（OpenAI）、thinking（Anthropic）或 reasoning（Responses）时，平台不会覆盖。

7. 图片/视频/音频生成

8. 用量查询

8.1 账单用量

curl "https://api.example.com/v1/dashboard/billing/usage" \
  -H "Authorization: Bearer $API_KEY"

返回该 key 的累计用量，包括 prompt/completion/total token、请求数与时间戳。未提供 key 时按 anonymous 口径处理，不会返回 401。

8.2 估算 token

curl https://api.example.com/v1/token/count \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "估算这段文本的 token 数"}]
  }'

这是粗略估算（基于字符数），不调用真实 tokenizer，仅用于 UI 提示，不要用于精确计费。

9. 错误与限流

错误体遵循请求协议：OpenAI 路径返回 {"error":{"message","type","code"}}，Anthropic 路径返回 {"type":"error","error":{...}}。上下文超限等不可重试错误会被归一化，便于客户端统一处理。

10. SDK 示例

10.1 OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="YOUR_API_KEY",
)

# 非流式
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "继续"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

10.2 Anthropic Python SDK

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.example.com",
    api_key="YOUR_API_KEY",
)

resp = client.messages.create(
    model="claude-3-5-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)

11. 安全与运维建议

• 客户端只通过 HTTPS 调用，并校验证书；不要为绕过证书问题关闭验证。
• 不同环境（开发/预发布/生产）使用不同 API Key，避免一个 key 泄漏影响全部环境。
• 对高频客户端设置合理超时、连接复用和退避；流式请求保持 SSE 连接稳定，避免频繁断开重连。
• 生产前先发非流式、流式、工具调用、错误场景四类请求，验证路由、用量与日志符合预期。
• 不要用 ?token= 方式把 key 放进 URL；优先使用请求头。
• 遇到 429/5xx 时，参考平台文档实现指数退避；不要立即重试放大流量。