相容 OpenAI Chat Completions 協議, 一套介面呼叫 Claude / Gemini 等主流大模型
POST /v1/chat/completions
鉴权: {'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
}'