Chat Completions

Chat Completions 是最常用的對話介面，適合一般聊天、程式設計助理、摘要、分類、工具呼叫和多輪對話。

它遵循 OpenAI Chat Completions 協定，既有的 OpenAI 接入只需替換 Base URL 和 API Key。同一個端點也能呼叫 Claude、Gemini 等模型，協定差異由 RouteAPI 在內部轉換。

Endpoint

POST /v1/chat/completions

完整位址：

https://api.routeapi.ai/v1/chat/completions

如果客戶端把 Base URL 設成不含 /v1（例如 https://api.routeapi.ai），存取 /chat/completions 也可以，RouteAPI 會將它改寫成 /v1/chat/completions。

請求範例

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "請用一句話介紹 RouteAPI" }
    ]
  }'

請求參數

欄位	類型	必填	說明
`model`	string	是	模型 ID，必須是當前帳戶可用模型
`messages`	array	是	對話訊息列表
`stream`	boolean	否	是否使用 SSE 串流輸出，預設 `false`
`temperature`	number	否	取樣溫度
`top_p`	number	否	nucleus sampling 參數
`max_tokens`	number	否	最大輸出 token 數
`max_completion_tokens`	number	否	輸出上限的新欄位名；與 `max_tokens` 同時存在時，RouteAPI 自身的上限判斷與計量以它為準
`stop`	string/array	否	自訂停止序列
`n`	integer	否	生成候選數；是否真的回傳多個候選取決於模型
`presence_penalty`	number	否	存在懲罰
`frequency_penalty`	number	否	頻率懲罰
`seed`	number	否	盡力而為的取樣種子；能否重現取決於上游模型
`user`	string	否	終端使用者標識，會透傳給支援該欄位的上游
`tools`	array	否	工具定義
`tool_choice`	string/object	否	工具選擇策略
`response_format`	object	否	JSON mode 或 JSON Schema
`stream_options`	object	否	串流輸出附加選項，例如 `include_usage`

選填欄位按原樣轉發：未傳的欄位不會被補上預設值。詳見下文「顯式零值」。

messages 格式

[
  { "role": "system", "content": "你是一個嚴謹的技術助手。" },
  { "role": "user", "content": "解釋什麼是 API 網關。" }
]

常見 role：

Role	說明
`system`	系統提示詞
`user`	使用者輸入
`assistant`	模型歷史回覆
`tool`	工具呼叫結果

content 可以是純字串，也可以是內容區塊陣列，用於多模態輸入，見多模態輸入。assistant 訊息回傳工具呼叫時，需要把該訊息原樣傳回，再追加 role: "tool" 的結果，見工具呼叫。

回應範例

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RouteAPI 是一個統一管理多家 AI 模型供應商的 API 網關。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

finish_reason 表示生成結束的原因：stop（自然結束）、length（達到輸出上限）、tool_calls（模型請求呼叫工具）、content_filter（被內容過濾攔截）。

串流輸出

設定 stream: true 後回傳 Server-Sent Events。每行是一個 chat.completion.chunk，增量內容在 choices[0].delta 裡，串流以 data: [DONE] 結束：

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"RouteAPI"},"finish_reason":null}]}

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

預設情況下，RouteAPI 會在 data: [DONE] 之前追加一個攜帶 token 用量、choices 為空的資料塊。傳 "stream_options": {"include_usage": false} 可將其關閉（不支援 stream_options 的渠道則始終回傳）；用量仍會記錄在控制台日誌裡。完整的逐事件處理與串流中的錯誤見串流回應。

SDK 設定

官方 OpenAI SDK 只需把 API Key 和 Base URL 指向 RouteAPI，其餘程式碼不用改。

OpenAI Python SDK

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "請用一句話介紹 RouteAPI"}],
)

print(response.choices[0].message.content)

OpenAI Node.js SDK

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: '請用一句話介紹 RouteAPI' }],
});

console.log(response.choices[0].message.content);

LangChain 與 LiteLLM

這兩個函式庫都支援自訂 OpenAI 相容端點：

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.5",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

import os
import litellm

response = litellm.completion(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "請用一句話介紹 RouteAPI"}],
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
)

其他相容客戶端

任何支援自訂 OpenAI Base URL 的客戶端，用同樣三項設定即可接入：

API Key — sk- 開頭的 RouteAPI API Key。
Base URL — https://api.routeapi.ai/v1。
模型 — GET /v1/models 回傳的模型 ID，見 Models。

Codex、Cursor、Claude Code、OpenCode 等工具的現成設定見從 OpenAI 遷移。

與官方 OpenAI API 的差異

模型範圍更廣

官方 OpenAI API 只能呼叫 OpenAI 自家模型。這裡的 model 欄位可以填多家供應商的模型，例如 gpt-5.5、claude-sonnet-4-5、gemini-2.5-pro，具體取決於你的 Key 和分組能用哪些。能呼叫哪些模型只能以 GET /v1/models 的回傳為準。

計費與限流由 RouteAPI 管理

計費按 RouteAPI 的價格表，可能與供應商官方價格不同。
限流按 RouteAPI 的策略，而不是供應商自己的限額。
餘額與 Key 額度都在 RouteAPI 控制台管理。

詳見計費與額度和模型定價。

能力取決於所選模型

協定只定義欄位，欄位是否真正生效取決於模型。工具呼叫、圖像輸入、結構化輸出、串流用量和推理控制都取決於所選模型及其背後的上游服務。模型列表介面不返回能力標記，依賴某項能力前請先用一次真實請求驗證。

顯式零值

明確傳入 0、0.0 或 false 的選填參數會被保留並轉發，不會因為「值是 0」被當作未設定丟棄。這樣可以固定 temperature: 0 做確定性取樣。想讓某個參數保持未設定，直接刪掉該欄位，不要傳 null。

上游錯誤

模型服務拒絕請求時，RouteAPI 回傳上游的狀態碼和訊息，使用標準錯誤結構，並在 message 末尾附加 (request id: <id>)。路由之前產生的錯誤——Key 無效、模型無權限、無可用渠道——使用常見錯誤裡列出的錯誤碼。

相容性提醒

同一個參數在不同模型服務中的支援程度可能不同。
如果請求包含 tools、response_format、stream_options 等選填參數，請先確認所選模型支援對應能力。
明確傳入 0 或 false 的選填參數應被視為使用者顯式設定。
結構化輸出與工具呼叫一起使用時，先閱讀結構化輸出裡的約束。

下一步

Responses — 更新的 OpenAI 協定，編碼代理常用。
Claude Messages — Anthropic 原生格式，可用 Claude 專有能力。
Google Gemini API — Google 原生格式。
Models — 你的 Key 能呼叫哪些模型及其端點類型。