开发文档

agent-router 同时兼容 OpenAI 与 Anthropic 协议,一个 Key 即可访问当前已上线的主流大模型。 本页是完整的接口参考,所有代码片段都可一键复制。

API v1 · 统一接入兼容 OpenAI / Anthropic SDK

概览

agent-router 是一条聚合接入多家模型厂商的统一推理通道,同时兼容 OpenAI 的/v1/chat/completions、/v1/responses 与 Anthropic 的 /v1/messages 协议。任何能接受自定义base_url 的 SDK 或 HTTP 客户端(OpenAI SDK、Anthropic SDK、Claude Code CLI 等), 通常只需修改接入地址、API Key 与模型 ID 即可切换到本网关。

下面三种集成方式选一种开始:

快速开始

三步走:拿到 Key、指向 Base URL、发一次请求。

1. 获取 API Key

  1. 打开 API Keys 控制台,登录或注册账号。
  2. 点击「创建密钥」,命名后复制生成的 sk-... 字符串。
  3. 在「额度」页面充值,确保账户有可用余额。
Key 仅展示一次
创建完成后 Key 仅明文展示一次。请妥善保存到密码管理器或服务端密钥存储,切勿提交到源码仓库或放入前端代码。

2. 验证连接

用你最熟悉的语言跑一次下面的代码,把 your_api_key 替换成真实 Key:

curl http://api.agent-router.cn/v1/chat/completions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [{ "role": "user", "content": "你好" }]
  }'

成功响应长这样:

200 OK
{
  "id": "chatcmpl-9f2abc123",
  "object": "chat.completion",
  "created": 1716240000,
  "model": "qwen3.7-max",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好!有什么可以帮你?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 11, "total_tokens": 20 }
}
常见报错
  • 401 通常是 Key 错误或已停用。
  • 404 一般是 Base URL 忘了 /v1 后缀。
  • 402 是余额不足,到控制台充值即可。

基础信息

参数类型必填说明
网关地址HTTP是
http://api.agent-router.cn
OpenAI SDK Base URLstring是
http://api.agent-router.cn/v1
OpenAI HTTP 生成端点string是
/v1/chat/completions 或 /v1/responses
Anthropic SDK / CLI Base URLstring是
http://api.agent-router.cn
Anthropic HTTP 端点string是
http://api.agent-router.cn/v1/messages
协议HTTP是
通过 HTTP 访问当前网关地址。
编码UTF-8是
请求 / 响应统一 UTF-8。
Content-Typeapplication/json是
除流式响应为 text/event-stream 外均为 JSON。
当前地址未启用 TLS
当前网关使用明文 HTTP,Bearer Key 和请求内容不会在传输层加密。请仅在可信网络中使用; 若需通过公网或不可信网络访问,应先为网关配置 HTTPS,切勿直接发送生产密钥或敏感数据。

鉴权

所有接口通过 HTTP Authorization 请求头携带 Bearer Token 鉴权:

Request Header
Authorization: Bearer your_api_key

Key 与账户强绑定,可在控制台随时轮换。推荐在服务端将 Key 放入环境变量, 通过后端代理请求,不要将 Key 下发到浏览器或移动端。

对话补全

agent-router 的 OpenAI 兼容接口,支持常用的对话补全字段。不同模型的参数与能力可能不同, 网关会丢弃上游不支持的可选参数。

POSThttp://api.agent-router.cn/v1/chat/completions

请求参数

参数类型必填说明
modelstring是
模型 ID,例如 qwen3.7-max、deepseek-v3.2、glm-5,完整列表以 模型列表接口返回为准。
messagesarray是
对话消息数组,每条包含 role(system/user/assistant/tool)与 content。
temperaturenumber否
采样温度,0–2。值越大输出越发散。
默认值:1
max_tokensinteger否
输出 token 上限。推理类模型的隐藏思考 token 会占用该额度, 若上限过低可能返回空 content 且 finish_reason="length"。
streamboolean否
设为 true 时响应为 SSE 流式增量。详见 流式输出。
默认值:false
tools / tool_choiceobject否
OpenAI 兼容的函数调用字段;是否可用取决于所选模型。详见 函数调用。
top_p / stop / seed / response_format多种否
常用兼容字段。模型不支持的可选参数可能被网关忽略或丢弃。
session_idstring否
可选的调用方会话标识,用于调用日志、审计筛选与会话分组;不会替客户端保存上下文。

请求示例

curl http://api.agent-router.cn/v1/chat/completions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [
      { "role": "system", "content": "你是一个严谨的资深工程师。" },
      { "role": "user",   "content": "用一句话解释量子纠缠。" }
    ],
    "temperature": 0.5
  }'

响应结构

200 OK
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1738960610,
  "model": "deepseek-v3.2",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "两个粒子的量子态无论相距多远都会同步变化。" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

Responses 接口(OpenAI)

Responses API 使用 input 接收字符串或 typed Items,并在 output中返回消息、推理或工具调用等不同类型的 Item。它与 Chat Completions 的messages / choices 结构不同,适合新的 OpenAI SDK 与 Agent 客户端。

POSThttp://api.agent-router.cn/v1/responses

请求参数

参数类型必填说明
modelstring是
模型 ID,以 模型列表接口返回为准。
inputstring / array是
输入文本或 typed Items 数组。简单场景可直接传字符串;多轮或多模态场景使用 Item 数组。
instructionsstring否
本次请求的顶层系统指令。
max_output_tokensinteger否
本次请求允许生成的最大 token 数,包括可见输出与推理 token。
streamboolean否
设为 true 时返回 Responses typed SSE 事件。
默认值:false
tools / tool_choicearray / object否
Responses 风格的工具定义与选择策略;是否可用取决于模型及上游。
textobject否
文本输出配置;结构化输出使用 text.format,不使用 Chat Completions 的 response_format。
previous_response_idstring否
可选的上一次响应 ID,仅在所选模型与上游支持有状态串联时使用。
session_idstring否
可选的日志、审计与会话分组标识;不会自动保存或串联对话上下文。
兼容范围取决于模型
网关会为部分上游模型做协议转换,因此不应假定每个模型都支持 OpenAI 托管工具、previous_response_id、多模态输入或结构化输出。接入前请对目标模型和所需字段分别验证。

请求示例

cURL
curl http://api.agent-router.cn/v1/responses \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "instructions": "请用简洁的中文回答。",
    "input": "用一句话解释量子纠缠。",
    "session_id": "chat-20260728-001",
    "max_output_tokens": 512
  }'

响应结构

200 OK
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1786370102,
  "status": "completed",
  "model": "qwen3.7-max",
  "output": [
    {
      "id": "msg_...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "量子纠缠是多个粒子共享同一量子态,使它们的测量结果表现出强相关性。",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 22,
    "output_tokens": 31,
    "total_tokens": 53
  }
}

OpenAI SDK 可通过 response.output_text 读取聚合后的文本。直接处理 JSON 时应遍历output 并按 type 分支,不要假定第一个 Item 一定是文本消息。

消息接口(Anthropic Messages)

Anthropic 兼容接口使用原生 Messages 请求与响应结构。直接通过 HTTP 调用时,请求地址必须包含/v1/messages,并携带 anthropic-version 请求头。

POSThttp://api.agent-router.cn/v1/messages

请求参数

参数类型必填说明
modelstring是
模型 ID,以 模型列表接口返回为准;协议及工具能力可能因模型而异。
messagesarray是
消息数组,role 使用 user 或 assistant;content 可为字符串或 content blocks 数组。
max_tokensinteger是
本次请求允许生成的最大 token 数。
systemstring / array否
顶层 system prompt;不要将 system 当作 messages[].role。
streamboolean否
设为 true 时返回 Anthropic 风格 SSE 事件。
默认值:false
tools / tool_choicearray / object否
Anthropic 工具定义与选择策略;是否可用取决于所选模型。
temperature / top_p / stop_sequences多种否
常用采样与停止参数;具体取值和兼容性以模型实际响应为准。
session_idstring否
可选的日志与审计分组标识,不会自动维护对话上下文。

请求示例

cURL
curl http://api.agent-router.cn/v1/messages \
  -H "Authorization: Bearer your_api_key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "system": "请用简洁的中文回答。",
    "session_id": "chat-20260728-001",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"用一句话解释量子纠缠。"}]
  }'

响应结构

200 OK
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-v3.2",
  "content": [
    {
      "type": "text",
      "text": "量子纠缠是多个粒子共享同一量子态,使它们的测量结果表现出强相关性。"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 32
  }
}

文本响应通常从 content[].type === "text" 的 block 中读取。启用工具后,content 也可能包含 tool_use 等其他 block,应按 type 分支处理。

流式输出

在请求体中设置 stream: true,响应即变为 Server-Sent Events 流。/v1/chat/completions 返回 OpenAI chat.completion.chunk,最后以data: [DONE] 结束;/v1/responses 返回 response.created、response.output_text.delta 与 response.completed 等 typed 事件;/v1/messages 返回 Anthropic 风格的message_start、content_block_delta、message_delta 与message_stop 事件。

stream = client.chat.completions.create(
    model="qwen3.7-max",
    messages=[{"role": "user", "content": "写一首关于大海的短诗"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
断线处理
SSE 长连接可能受网络或代理影响中断。三种协议的事件结构不同,不要假定断线后可从任意事件续传。 客户端应保留已接收的部分输出,并在重试时做好重复请求与重复文本处理。

函数调用(Chat Completions)

以下示例适用于 /v1/chat/completions。通过 tools 字段声明可调用的函数集合, 模型返回 tool_calls 后由业务代码执行并回传结果。Responses 的函数定义和返回 Item 结构不同, 不要直接复用下面的 JSON 形状。

request.json
{
  "model": "qwen3.7-max",
  "messages": [{ "role": "user", "content": "上海现在天气怎么样?" }],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "根据城市名返回天气",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

模型列表

GEThttp://api.agent-router.cn/v1/models

返回当前 API Key 可访问的模型清单,结构与 OpenAI 一致。模型上下线会变化,请以该接口的data[].id 为准,不要在客户端长期硬编码完整列表。

cURL
curl http://api.agent-router.cn/v1/models \
  -H "Authorization: Bearer your_api_key"
200 OK
{
  "object": "list",
  "data": [
    { "id": "qwen3.7-max",             "object": "model", "owned_by": "openai" },
    { "id": "deepseek-v3.2",           "object": "model", "owned_by": "openai" },
    { "id": "glm-5",                   "object": "model", "owned_by": "openai" },
    { "id": "doubao-seed-2-0-pro-260215", "object": "model", "owned_by": "openai" },
    { "id": "deepseek-v4-pro",        "object": "model", "owned_by": "deepseek" }
  ]
}
模型能力以实际响应为准
列表中的模型 ID 可用于发起测试,但不代表每个模型都支持两种协议的全部参数、工具调用或图像生成。 接入前请分别验证目标端点和所需能力,并妥善处理 400、429 与上游错误。

图像生成

POSThttp://api.agent-router.cn/v1/images/generations
Seedream 5.0 文生图
curl http://api.agent-router.cn/v1/images/generations \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A calico dog playing a piano on stage",
    "size": "2048x2048",
    "n": 1
  }'
文生图
curl http://api.agent-router.cn/v1/images/generations \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "A calico dog playing a piano on stage",
    "size": "2048x2048",
    "n": 1
  }'
Qwen Image Plus 文生图
curl http://api.agent-router.cn/v1/images/generations \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-plus",
    "prompt": "A calico dog playing a piano on stage",
    "n": 1
  }'

图像编辑

POSThttp://api.agent-router.cn/v1/images/edits

Seedream 5.0 与 Seedream 4.5 均支持图生图和多参考图生成。

单图编辑
curl http://api.agent-router.cn/v1/images/edits \
  -H "Authorization: Bearer your_api_key" \
  -F "model=doubao-seedream-5-0-260128" \
  -F "image=@otter.png" \
  -F "mask=@mask.png" \
  -F "prompt=Add a small dog in the bottom-right corner."
上传限制
图像编辑上传文件时,单次请求体不得超过网关配置的 50 MB。

Python SDK

直接使用 OpenAI 官方 openai 包,把 base_url 指向网关即可:

安装
pip install openai
app.py
from openai import OpenAI

client = OpenAI(
    api_key="your_api_key",
    base_url="http://api.agent-router.cn/v1",
)

resp = client.chat.completions.create(
    model="qwen3.7-max",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in resp:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Node.js SDK

安装
npm install openai
app.mjs
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LLM_GATEWAY_KEY,
  baseURL: "http://api.agent-router.cn/v1",
});

const resp = await client.chat.completions.create({
  model: "qwen3.7-max",
  messages: [{ role: "user", content: "用中文介绍一下 RAG" }],
});
console.log(resp.choices[0].message.content);

Anthropic SDK

想保留 Anthropic 的原生消息格式(system 顶层字段、content 数组、stop_reason 等)?把官方 anthropic SDK 的 base_url 指向 http://api.agent-router.cn。SDK 会自动追加 /v1/messages; 模型名使用 GET /v1/models 返回的 ID (具体模型 ID 以模型广场或模型列表接口返回为准)。

Python 安装
pip install anthropic
claude.py
from anthropic import Anthropic

client = Anthropic(
    api_key="your_api_key",
    base_url="http://api.agent-router.cn",
)

msg = client.messages.create(
    model="deepseek-v3.2",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)
Node.js 安装
npm install @anthropic-ai/sdk
claude.mjs
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.LLM_GATEWAY_KEY,
  baseURL: "http://api.agent-router.cn",
});

const msg = await client.messages.create({
  model: "deepseek-v3.2",
  max_tokens: 1024,
  messages: [{ role: "user", content: "用一句话解释提示缓存" }],
});
console.log(msg.content[0].text);

也可直接 POST http://api.agent-router.cn/v1/messages(同 Anthropic 公网协议,带anthropic-version: 2023-06-01 头)。流式请求加上 stream: true, 返回的是 Anthropic 风格的 message_start / content_block_delta / message_delta 事件。

cURL / 任意语言

只要能发 HTTP 请求,任何语言都可调用。根据客户端期望的请求与响应结构选择 OpenAI 或 Anthropic 端点;具体模型与参数能力以实际响应为准。

OpenAI 协议
curl http://api.agent-router.cn/v1/chat/completions \
  -H "Authorization: Bearer $LLM_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen3.7-max", "session_id": "chat-20260728-001", "messages": [{"role":"user","content":"Hi"}] }'
OpenAI Responses
curl http://api.agent-router.cn/v1/responses \
  -H "Authorization: Bearer $LLM_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen3.7-max", "session_id": "chat-20260728-001", "input": "Hi" }'
Anthropic Messages
curl http://api.agent-router.cn/v1/messages \
  -H "Authorization: Bearer $LLM_GATEWAY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "deepseek-v3.2", "session_id": "chat-20260728-001", "max_tokens": 1024, "messages": [{"role":"user","content":"Hi"}] }'

session_id 只用于调用日志、审计筛选与会话分组,不会让接口变成有状态服务。 多轮对话需通过 messages、Responses Items 或经验证可用的previous_response_id 显式传递上下文。

Claude Code CLI

Claude Code CLI 可通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN接入 agent-router。推荐同时设置 ANTHROPIC_MODEL,模型名填写模型广场里的 API ID。

$env:LLM_GATEWAY_KEY = "sk-your_api_key"
$env:ANTHROPIC_AUTH_TOKEN = $env:LLM_GATEWAY_KEY
$env:ANTHROPIC_BASE_URL = "http://api.agent-router.cn"
$env:ANTHROPIC_MODEL = "deepseek-v3.2"

claude
Windows 验证
进入 Claude Code 后运行 /status,确认 Anthropic base URL 指向网关; 再到控制台「调用日志」查看刚才的请求是否出现。

Codex / VS Code

Codex CLI 及其 VS Code 插件读取 OPENAI_BASE_URL 与 OPENAI_API_KEY:

~/.zshrc
export LLM_GATEWAY_KEY="sk-your_api_key"
export OPENAI_API_KEY="$LLM_GATEWAY_KEY"
export OPENAI_BASE_URL="http://api.agent-router.cn/v1"

codex
在 VS Code 中
安装 Codex 扩展后,在 settings.json 中把 codex.baseUrl 填为http://api.agent-router.cn/v1,codex.apiKey 填入你的 Gateway Key 即可。

错误码参考

参数类型必填说明
400Bad Request否
请求体格式错误、未知模型或参数不被支持。核对模型 ID 是否区分大小写。
401Unauthorized否
API Key 无效、缺失或已被撤销。请前往控制台检查 Authorization 头。
402Payment Required否
余额不足。到「额度」页面充值后重试。
404Not Found否
Base URL 或接口路径不正确。OpenAI SDK 使用带 /v1 的 Base URL,Anthropic SDK 使用网关根地址。
429Too Many Requests否
触发速率限制。建议指数退避,或把负载分散到多个模型。
500 / 502 / 504Server Error否
上游模型或网关暂时不可用,建议重试或切换模型。

速率限制

网关或上游模型可能在并发、请求速率或容量不足时返回 429。不同模型和上游的限制可能不同, 不要依赖固定的 RPM 数值或某组响应头。

若响应包含 Retry-After,客户端应按该值等待;否则使用带随机抖动的指数退避, 并设置最大重试次数,避免放大上游故障。

还有问题?
任何字段或行为与 OpenAI 官方文档存在差异时,本文档为准。遇到无法解释的错误, 若响应包含 x-request-id,可以把它发给 技术支持,我们会按单排查。