供应商路由

一个模型通常由多个供应商承载，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`	供应商存在，但未承载该模型。错误信息中会一并列出承载该模型的供应商。

可以指定哪些供应商

完整列表，以及如何查询某个模型由哪些供应商承载，见供应商路由。