供應商路由

一個模型通常由多個供應商承載，provider.type 用於將請求鎖定到其中一個。有哪些供應商、以及為什麼要指定，見供應商路由；本頁是各協議的欄位契約。

欄位位置

該欄位在各協議下的位置並不一致：

協議 / 端點	請求主體	請求標頭
OpenAI Chat Completions · `POST /v1/chat/completions`	`extra_body.provider.type`	`X-OfoxAI-Provider-Type`
OpenAI Responses · `POST /v1/responses`	`extra_body.provider.type`	`X-OfoxAI-Provider-Type`
OpenAI Images · `POST /v1/images/generations`	`extra_body.provider.type`	`X-OfoxAI-Provider-Type`
Anthropic Messages · `POST /anthropic/v1/messages`	`extra_body.provider.type`	`X-OfoxAI-Provider-Type`
Gemini generateContent · `POST /gemini/v1beta/…`	靜默忽略	`X-OfoxAI-Provider-Type`
Video API · `POST /v1/videos`	最上層 `provider.type`	—

生圖模型中目前只有 openai/gpt-image-2 由多個供應商承載（azure_foundry 與 openai），其餘均為單一供應商，指定其他供應商會回傳 400 provider_type_unavailable。另需注意 Gemini 系生圖模型有兩個協議入口 —— 走 /v1/images/generations 時請求主體寫法有效，走 Gemini 原生 generateContent 時會被忽略。

透過請求主體傳遞

extra_body 需作為 JSON 請求主體中的字面量鍵存在，provider 巢狀於其內：

cURL

Terminal


curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": { "type": "bedrock" }
    }
  }'

Python

provider_routing.py


client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={"extra_body": {"provider": {"type": "bedrock"}}},
)

TypeScript

provider-routing.ts


await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: { provider: { type: 'bedrock' } },
} as any)

使用官方 OpenAI SDK 時，extra_body 需作為請求主體中的字面量鍵存在。TypeScript SDK 在參數物件中直接書寫 extra_body 即可；Python SDK 的 extra_body= 參數會將其內容合併至請求主體最上層，因此需額外巢狀一層，或改用請求標頭傳遞。

Gemini 原生協議會忽略請求主體中的 extra_body.provider —— 請求正常回傳，約束不生效，且沒有任何錯誤。該協議請改用下方的請求標頭。

透過請求標頭傳遞

X-OfoxAI-Provider-Type 在全部文字協議上均生效（含 Gemini），適合無法修改請求主體的接入方式：

Terminal


curl https://api.ofox.io/gemini/v1beta/models/google/gemini-3.1-flash-lite:generateContent \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "X-OfoxAI-Provider-Type: vertex" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "..." }] }]
  }'

在兩者都支援的協議上，請求標頭與請求主體欄位等價。Video API 沒有請求標頭寫法，見 Video API · 供應商路由。

錯誤

`error.type`	觸發條件
`invalid_provider_type`	取值不是供應商名稱：拼寫錯誤，或使用了已淘汰的寫法。
`provider_type_unavailable`	供應商存在，但未承載該模型。錯誤訊息中會一併列出承載該模型的供應商。

可以指定哪些供應商

完整清單，以及如何查詢某個模型由哪些供應商承載，見供應商路由。