开发文档
agent-router 同时兼容 OpenAI 与 Anthropic 协议,一个 Key 即可访问当前已上线的主流大模型。 本页是完整的接口参考,所有代码片段都可一键复制。
概览
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 即可切换到本网关。
下面三种集成方式选一种开始:
任何能发 HTTP 请求的语言都能直接调用。
查看示例 →OpenAI 与 Anthropic 官方 SDK 都可直接接入,只需改一行 base_url。
查看 SDK →Claude Code、Codex、VS Code 等终端 Agent 一键接入。
查看配置 →快速开始
三步走:拿到 Key、指向 Base URL、发一次请求。
1. 获取 API Key
- 打开 API Keys 控制台,登录或注册账号。
- 点击「创建密钥」,命名后复制生成的
sk-...字符串。 - 在「额度」页面充值,确保账户有可用余额。
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": "你好" }]
}'成功响应长这样:
{
"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 URL | string | 是 | http://api.agent-router.cn/v1 |
OpenAI HTTP 生成端点 | string | 是 | /v1/chat/completions 或 /v1/responses |
Anthropic SDK / CLI Base URL | string | 是 | http://api.agent-router.cn |
Anthropic HTTP 端点 | string | 是 | http://api.agent-router.cn/v1/messages |
协议 | HTTP | 是 | 通过 HTTP 访问当前网关地址。 |
编码 | UTF-8 | 是 | 请求 / 响应统一 UTF-8。 |
Content-Type | application/json | 是 | 除流式响应为 text/event-stream 外均为 JSON。 |
鉴权
所有接口通过 HTTP Authorization 请求头携带 Bearer Token 鉴权:
Authorization: Bearer your_api_keyKey 与账户强绑定,可在控制台随时轮换。推荐在服务端将 Key 放入环境变量, 通过后端代理请求,不要将 Key 下发到浏览器或移动端。
对话补全
agent-router 的 OpenAI 兼容接口,支持常用的对话补全字段。不同模型的参数与能力可能不同, 网关会丢弃上游不支持的可选参数。
http://api.agent-router.cn/v1/chat/completions请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | |
messages | array | 是 | 对话消息数组,每条包含 role(system/user/assistant/tool)与 content。 |
temperature | number | 否 | 采样温度,0–2。值越大输出越发散。 默认值: 1 |
max_tokens | integer | 否 | 输出 token 上限。推理类模型的隐藏思考 token 会占用该额度, 若上限过低可能返回空 content 且 finish_reason="length"。 |
stream | boolean | 否 | 设为 true 时响应为 SSE 流式增量。详见 流式输出。默认值: false |
tools / tool_choice | object | 否 | OpenAI 兼容的函数调用字段;是否可用取决于所选模型。详见 函数调用。 |
top_p / stop / seed / response_format | 多种 | 否 | 常用兼容字段。模型不支持的可选参数可能被网关忽略或丢弃。 |
session_id | string | 否 | 可选的调用方会话标识,用于调用日志、审计筛选与会话分组;不会替客户端保存上下文。 |
请求示例
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
}'响应结构
{
"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 客户端。
http://api.agent-router.cn/v1/responses请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID,以 模型列表接口返回为准。 |
input | string / array | 是 | 输入文本或 typed Items 数组。简单场景可直接传字符串;多轮或多模态场景使用 Item 数组。 |
instructions | string | 否 | 本次请求的顶层系统指令。 |
max_output_tokens | integer | 否 | 本次请求允许生成的最大 token 数,包括可见输出与推理 token。 |
stream | boolean | 否 | 设为 true 时返回 Responses typed SSE 事件。默认值: false |
tools / tool_choice | array / object | 否 | Responses 风格的工具定义与选择策略;是否可用取决于模型及上游。 |
text | object | 否 | 文本输出配置;结构化输出使用 text.format,不使用 Chat Completions 的 response_format。 |
previous_response_id | string | 否 | 可选的上一次响应 ID,仅在所选模型与上游支持有状态串联时使用。 |
session_id | string | 否 | 可选的日志、审计与会话分组标识;不会自动保存或串联对话上下文。 |
previous_response_id、多模态输入或结构化输出。接入前请对目标模型和所需字段分别验证。请求示例
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
}'响应结构
{
"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 请求头。
http://api.agent-router.cn/v1/messages请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID,以 模型列表接口返回为准;协议及工具能力可能因模型而异。 |
messages | array | 是 | 消息数组, role 使用 user 或 assistant;content 可为字符串或 content blocks 数组。 |
max_tokens | integer | 是 | 本次请求允许生成的最大 token 数。 |
system | string / array | 否 | 顶层 system prompt;不要将 system 当作 messages[].role。 |
stream | boolean | 否 | 设为 true 时返回 Anthropic 风格 SSE 事件。 默认值: false |
tools / tool_choice | array / object | 否 | Anthropic 工具定义与选择策略;是否可用取决于所选模型。 |
temperature / top_p / stop_sequences | 多种 | 否 | 常用采样与停止参数;具体取值和兼容性以模型实际响应为准。 |
session_id | string | 否 | 可选的日志与审计分组标识,不会自动维护对话上下文。 |
请求示例
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":"用一句话解释量子纠缠。"}]
}'响应结构
{
"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)函数调用(Chat Completions)
以下示例适用于 /v1/chat/completions。通过 tools 字段声明可调用的函数集合, 模型返回 tool_calls 后由业务代码执行并回传结果。Responses 的函数定义和返回 Item 结构不同, 不要直接复用下面的 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"
}模型列表
http://api.agent-router.cn/v1/models返回当前 API Key 可访问的模型清单,结构与 OpenAI 一致。模型上下线会变化,请以该接口的data[].id 为准,不要在客户端长期硬编码完整列表。
curl http://api.agent-router.cn/v1/models \
-H "Authorization: Bearer your_api_key"{
"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" }
]
}400、429 与上游错误。图像生成
http://api.agent-router.cn/v1/images/generationscurl 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
}'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
}'图像编辑
http://api.agent-router.cn/v1/images/editsSeedream 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."Python SDK
直接使用 OpenAI 官方 openai 包,把 base_url 指向网关即可:
pip install openaifrom 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 openaiimport 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 以模型广场或模型列表接口返回为准)。
pip install anthropicfrom 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)npm install @anthropic-ai/sdkimport 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 端点;具体模型与参数能力以实际响应为准。
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"}] }'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" }'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/status,确认 Anthropic base URL 指向网关; 再到控制台「调用日志」查看刚才的请求是否出现。Codex / VS Code
Codex CLI 及其 VS Code 插件读取 OPENAI_BASE_URL 与 OPENAI_API_KEY:
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"
codexsettings.json 中把 codex.baseUrl 填为http://api.agent-router.cn/v1,codex.apiKey 填入你的 Gateway Key 即可。错误码参考
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
400 | Bad Request | 否 | 请求体格式错误、未知模型或参数不被支持。核对模型 ID 是否区分大小写。 |
401 | Unauthorized | 否 | API Key 无效、缺失或已被撤销。请前往控制台检查 Authorization 头。 |
402 | Payment Required | 否 | 余额不足。到「额度」页面充值后重试。 |
404 | Not Found | 否 | Base URL 或接口路径不正确。OpenAI SDK 使用带 /v1 的 Base URL,Anthropic SDK 使用网关根地址。 |
429 | Too Many Requests | 否 | 触发速率限制。建议指数退避,或把负载分散到多个模型。 |
500 / 502 / 504 | Server Error | 否 | 上游模型或网关暂时不可用,建议重试或切换模型。 |
速率限制
网关或上游模型可能在并发、请求速率或容量不足时返回 429。不同模型和上游的限制可能不同, 不要依赖固定的 RPM 数值或某组响应头。
若响应包含 Retry-After,客户端应按该值等待;否则使用带随机抖动的指数退避, 并设置最大重试次数,避免放大上游故障。
x-request-id,可以把它发给 技术支持,我们会按单排查。