공급자 라우팅

하나의 모델은 보통 여러 공급자가 제공하며, 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는 파라미터 객체에 작성한 그대로 전송합니다. 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`	공급자는 존재하지만 이 모델을 제공하지 않습니다. 메시지에 제공 가능한 공급자도 함께 표시됩니다.

지정할 수 있는 공급자

전체 목록과 특정 모델을 어떤 공급자가 제공하는지 확인하는 방법은 공급자 라우팅에 있습니다.