Roteamento de provedores

Um modelo costuma ser atendido por vários provedores, e provider.type fixa a requisição em um deles. Quais provedores existem e por que fixar um estão em Roteamento de provedores; esta página é o contrato de campo por protocolo.

Onde fica o campo

O campo não fica no mesmo lugar em todos os protocolos:

Protocolo / endpoint	Corpo da requisição	Cabeçalho
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/…`	ignorado silenciosamente	`X-OfoxAI-Provider-Type`
Video API · `POST /v1/videos`	`provider.type` de nível superior	—

Entre os modelos de imagem, hoje apenas openai/gpt-image-2 é atendido por mais de um provedor (azure_foundry e openai); os demais são de provedor único, então indicar outro retorna 400 provider_type_unavailable. Note também que os modelos de imagem do Gemini têm dois pontos de entrada — em /v1/images/generations o campo do corpo funciona; no generateContent nativo do Gemini ele é ignorado.

Enviando no corpo da requisição

extra_body precisa ser uma chave literal do corpo JSON, com provider aninhado dentro:

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)

Com os SDKs oficiais da OpenAI, extra_body precisa existir como chave literal no corpo da requisição. O SDK de TypeScript envia exatamente como está escrito no objeto de parâmetros. O argumento extra_body= do SDK de Python mescla o conteúdo no nível superior do corpo, então a chave precisa ser aninhada um nível a mais, ou enviada como cabeçalho.

O protocolo nativo do Gemini ignora extra_body.provider no corpo — a requisição é concluída, a restrição simplesmente não se aplica e não há erro algum. Nesse protocolo, use o cabeçalho abaixo.

Enviando em um cabeçalho

X-OfoxAI-Provider-Type funciona em todos os protocolos de texto, incluindo o Gemini, e serve para integrações que não conseguem alterar o corpo da requisição:

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": "..." }] }]
  }'

Onde ambos são suportados, o cabeçalho e o campo do corpo são equivalentes. A Video API não tem forma de cabeçalho — veja Video API · Roteamento de provedores.

Erros

`error.type`	Quando acontece
`invalid_provider_type`	O valor não é um nome de provedor: erro de digitação ou grafia descontinuada.
`provider_type_unavailable`	O provedor existe, mas não atende este modelo. A mensagem também lista os que atendem.

Quais provedores você pode indicar

A lista completa, e como descobrir quais provedores atendem um modelo, estão em Roteamento de provedores.