Models

模型列表介面回答一個問題：當前這個 Token 能呼叫哪些模型。返回的是按 Token 權限、分組和上架狀態過濾後的結果，不是平台全量模型目錄。請求中的 model 必須來自這個列表。

列出可用模型

GET /v1/models

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

回應：

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["embeddings"]
    }
  ]
}

欄位	說明
id	呼叫時填進 model 的值，唯一可靠的模型識別碼
object	固定為 "model"
created	固定佔位值 1626777600，不是真實上架時間，不要用它排序或判斷新舊
owned_by	模型所屬渠道類型（如 openai、anthropic）；平台自訂模型為 custom
supported_endpoint_types	該模型可用的端點類型列表，見下方端點類型

回應頂層同時有 success 和 OpenAI 風格的 object/data。OpenAI SDK 只讀 data，多出的 success 不影響解析。

data 的順序不保證穩定，兩次請求可能不同。需要固定順序請在用戶端自行排序。

端點類型

supported_endpoint_types 是 RouteAPI 的擴充欄位，也是模型列表裡唯一的能力訊號。它表示這個模型能從哪些協定入口呼叫：

值	對應端點
openai	POST /v1/chat/completions
openai-response	POST /v1/responses
anthropic	POST /v1/messages
gemini	POST /v1beta/models/{model}:generateContent
embeddings	POST /v1/embeddings
image-generation	POST /v1/images/generations
jina-rerank	POST /v1/rerank
openai-video	OpenAI 視訊生成端點
suno-*	Suno 系列端點，見 Suno API

如果一個模型的 supported_endpoint_types 裡沒有 embeddings，就不要把它傳給 /v1/embeddings——這類不匹配會在轉發階段失敗。

列表裡沒有細粒度能力欄位。 是否支援工具呼叫、圖像輸入、結構化輸出，模型列表介面不返回，也沒有 supports_tools / supports_vision 這類欄位。這些能力由上游模型自身決定，確認方式是查閱模型供應商文件，或直接用目標模型發一次真實請求驗證。上下文長度、模態和價格等元資料同樣不在這個介面裡，它們展示在控制台的模型廣場頁面。

查詢單個模型

GET /v1/models/{model}

curl https://api.routeapi.ai/v1/models/gpt-5.5 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

存在時直接返回模型物件（不包裹 data）：

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1626777600,
  "owned_by": "openai"
}

不存在或對當前帳戶不可見時返回：

{
  "error": {
    "message": "The model 'foo' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

注意 HTTP 狀態碼仍是 200。 這個介面把錯誤放在回應主體的 error 欄位裡，不用狀態碼表達「模型不存在」。用戶端必須檢查回應主體裡有沒有 error，只看 HTTP 狀態碼會把失敗當成功。

對當前帳戶不可見的模型與真正不存在的模型返回完全相同的錯誤，無法透過這個介面區分兩者。

其他協定的模型列表

同一份可用模型集合可以用三種協定格式取回，按你的 SDK 選擇即可。

Claude Messages 格式

在 GET /v1/models 上同時帶 x-api-key 和 anthropic-version 請求標頭，返回 Anthropic 風格：

curl https://api.routeapi.ai/v1/models \
  -H "x-api-key: $ROUTEAPI_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "id": "claude-sonnet-4-5",
      "created_at": "2021-07-20T12:00:00Z",
      "display_name": "claude-sonnet-4-5",
      "type": "model"
    }
  ],
  "first_id": "claude-sonnet-4-5",
  "has_more": false,
  "last_id": "claude-sonnet-4-5"
}

兩個請求標頭必須同時存在才會切換到這個格式，只帶 x-api-key 仍返回 OpenAI 格式。display_name 等於 id，不是控制台裡的展示名。has_more 恆為 false——列表一次返回完，沒有分頁。列表為空時 first_id 和 last_id 是空字串。

Gemini 格式

curl "https://api.routeapi.ai/v1beta/models" \
  -H "x-goog-api-key: $ROUTEAPI_KEY"

{
  "models": [
    { "name": "gemini-2.5-pro", "displayName": "gemini-2.5-pro" }
  ],
  "nextPageToken": null
}

Gemini 格式的模型物件還包含 inputTokenLimit、supportedGenerationMethods 等欄位，但 RouteAPI 只填充 name 和 displayName，其餘欄位返回 null。不要依賴這些空欄位判斷模型能力。

Gemini 協定的模型列表請用 /v1beta/models 路徑，不要在 /v1/models 上帶 Gemini 請求標頭。

不帶 /v1 前綴

用戶端把 Base URL 設成不帶 /v1（例如 https://api.routeapi.ai）時，GET /models 同樣可用，內部會改寫回 /v1/models。

決定列表內容的四道過濾

模型出現在你的列表裡，需要同時通過四道過濾。排查「模型不在列表中」時按這個順序看：

1. Token 模型白名單 — 如果這個 Token 啟用了模型限制，列表就是白名單與其餘條件的交集。未啟用則進入下一條。
2. 分組已啟用模型 — 取你所屬使用者分組（及 Token 指定分組）下已啟用的模型聯集。模型沒有任何可用渠道就不會出現。
3. 目錄上架狀態 — 平台開啟嚴格元資料模式時，未上架的模型對外等同不存在。
4. 是否已配價 — 未設定價格的模型預設被過濾掉，除非平台開了自用模式，或你的帳戶設定裡開啟了「接受未設價模型」。

四道過濾後返回空列表是正常結果，不是錯誤。分組內模型全部未上架時就會這樣。

同一個平台下，不同 Token 的模型列表可以完全不同。用 A Token 查列表、用 B Token 發請求是常見的踩坑方式——排查時務必用同一個 Token 做這兩件事。

模型不可用排查

請求報模型相關錯誤時，先對照錯誤文案定位到具體環節：

錯誤文案	HTTP	含義	處理
Model name not specified...	400	請求裡 model 為空	補上 model 欄位
This token has no access to model {model}	403	模型不在該 Token 的白名單裡	在控制台給 Token 加上該模型，或換一個不限模型的 Token
This token has no access to any models	403	Token 啟用了模型限制但白名單為空	補全白名單
No valid upstream service	503	模型無可用渠道（未設定、全部停用或熔斷中）	確認模型 ID 拼寫；換用列表裡的其他模型；聯絡平台管理員
The model '{model}' does not exist	200（主體內 error）	GET /v1/models/{model} 查不到或不可見	用 GET /v1/models 確認準確 ID

排查順序：

1. 用同一個 Token 呼叫 GET /v1/models，確認模型確實在列表裡。
2. 逐字元核對 model 拼寫，包括大小寫和連字號。模型 ID 嚴格匹配。
3. 確認呼叫的端點在該模型的 supported_endpoint_types 裡。
4. 以上都對但仍失敗，說明問題在渠道側（無可用上游或上游報錯），到控制台日誌按 request ID 查具體上游回應。詳見錯誤與除錯。

最佳實踐

• 固定模型 ID，不要用控制台展示名或臨時別名。請求只認 id。
• 啟動時拉一次列表並快取，不要每次業務請求都查。可用模型集合變化頻率很低。
• 不要用 created 排序，它是所有模型共享的固定佔位值。
• 關鍵鏈路準備備用模型，在主模型返回 503 時切換。
• 上線前用生產 Token 實測一次，模型列表和一次真實呼叫都要跑，覆蓋工具呼叫、圖像輸入等你實際用到的能力——這些能力列表介面不保證。

接下來

• 認證方式 — Token 權限、模型白名單和額度設定。
• Chat Completions — 用列表裡的模型發起對話。
• 錯誤與除錯 — 完整狀態碼與排查順序。
• 計費與額度 — 模型價格與用量口徑。