兼容 OpenAI Chat Completions 协议, 一套接口调用 Claude / Gemini 等主流大模型
POST /v1/chat/completions
Auth: {'type': 'bearer', 'prefix': 'sk-', 'description': 'API Key, 使用 `Authorization: Bearer sk-xxx` 鉴权'}
统一的对话补全接口, 请求 / 响应结构与 OpenAI 完全一致。已有使用 OpenAI SDK 的项目只需替换 `baseURL` 即可切换。 - 支持 `stream: true` SSE 流式推送 - `messages[].content` 支持字符串或多模态数组 (文本 + 图片 URL) - 工具调用 (tools / function calling) 同 OpenAI 规范
model | string | required | 要调用的模型 id。⚠️ 先调 GET /v1/models 取当前可用列表, 不要凭印象拼 —— 本网关不一定暴露与上游厂商相同的 id。id 全小写连字符、无空格 (kimi-k3 而非 Kimi K3)。 |
messages | array | required | 对话消息列表, 每项含 role 与 content。role 可为 system / user / assistant / tool。 |
role | string | required | |
content | string | required | 消息内容 (字符串, 或多模态数组 `[{"type":"text","text":"..."},{"type":"image_url","image_url":{"url":"..."}}]`) |
name | string | (可选) 消息作者标识 | |
tool_call_id | string | (仅 role=tool) 对应的 tool_call id | |
stream | boolean | 是否流式返回。true 时以 SSE 逐块推送, 适合需要边生成边展示的场景。 | |
temperature | number | 采样温度, 越大输出越发散、越小越稳定。 ⚠️ 推理类模型 (gpt-5 / o 系) 只接受默认值, 传其它值不会报错但不生效; 其它模型正常。 | |
max_tokens | integer | 本次回复最多生成多少 token。不传则由模型自行决定, 不会被截断。 | |
top_p | number | 核采样, 只在累计概率前 top_p 的候选里挑。与 temperature 选一个调即可。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
tools | array | 可供模型调用的工具列表。模型需要时会返回 tool_calls, 由你执行后把结果以 role=tool 回填。 | |
tool_choice | string | 控制是否/如何选用工具: auto 由模型决定, none 禁用, 也可指定某个具体工具。需与 tools 一起使用。 | |
response_format | object | 指定输出格式, 如要求返回 JSON。 | |
stop | array | 遇到其中任一字符串就停止生成, 该字符串不包含在结果里。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
n | integer | 一次返回几条候选回复。按全部候选的总用量计费。 | |
seed | integer | 固定随机种子, 相同输入尽量复现相同输出。 | |
frequency_penalty | number | 按 token 已出现频次降低其再次出现的概率, 用于抑制重复。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
presence_penalty | number | 按 token 是否已出现降低其再次出现的概率, 用于鼓励换话题。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
logit_bias | object | 按 token id 调整选中概率, 可用来强推或压制特定词。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
parallel_tool_calls | boolean | 是否允许模型一次返回多个工具调用。需与 tools 一起使用。 | |
logprobs | boolean | 是否返回所选 token 的对数概率。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
top_logprobs | integer | 每个位置额外返回多少个候选 token 的概率。需同时开启 logprobs。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
max_completion_tokens | integer | 输出 token 上限 (含推理过程 token + 可见输出 token)。⚠️ 对推理类模型设得太小时, 思考可能耗尽全部额度而正文为空 —— 此时 finish_reason=length 且 completion_tokens 等于 completion_tokens_details.reasoning_tokens。需要短回复请同时调低 reasoning_effort。部分较新模型用本字段替代 max_tokens。 | |
reasoning_effort | string | 推理强度。⚠️ 取值因模型而异, 本网关不做统一枚举: gpt-5.6 系实测支持 none / low / medium / high / xhigh (不支持 minimal), 其它推理模型可能不同。传了不支持的值上游会返 400, 且错误信息里会列出该模型支持的取值 —— 读它再重试即可。想要短回复又不被思考吃掉额度, 用支持的最低档 (如 none 可完全关闭思考)。仅推理类模型有效。 | |
verbosity | string | 回复详略程度。 | |
modalities | array | 期望的输出模态, 如仅文本或文本加音频。仅多模态模型有效。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
audio | object | 音频输出设置, 如音色与音频格式。需在 modalities 中包含音频。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
prediction | object | 预测输出。已知回复大部分内容时提供它可以加快生成。 ⚠️ 推理类模型 (gpt-5 / o 系) 不支持本参数, 传了不会报错但不生效; 其它模型正常。 | |
stream_options | object | 流式相关设置, 如是否在最后一帧附带用量统计。需 stream=true。 | |
store | boolean | 是否在模型服务侧留存本次对话。 | |
metadata | object | 自定义键值对, 会随请求一起带上, 便于你自己归类检索。 | |
user | string | 代表终端用户的标识, 便于你区分自己的用户来源。 | |
prompt_cache_key | string | 提示词缓存键。相同前缀的请求带同一个键更容易命中缓存, 从而更快更省。 | |
prompt_cache_retention | string | 提示词缓存保留时长。 |
200 — 返回 assistant 消息curl https://api.router.ai/v1/chat/completions \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"messages": [
{"role": "system", "content": "你是一位资深的技术写作助手"},
{"role": "user", "content": "用三句话介绍 Redis"}
],
"temperature": 0.7,
"max_tokens": 512
}'