메인 콘텐츠로 건너뛰기
OrcaRouter는 하나가 성공할 때까지 여러 모델을 순서대로 시도할 수 있습니다. 회복력(어떤 프로바이더가 스로틀되거나 다운된 경우)과 비용 제어(저렴한 모델을 우선하고 필요하면 강력한 모델로 폴백)에 유용합니다.

​
사용 방법

extra_body.models에 모델 ID의 순서 목록을 두고 extra_body.route를 "fallback"으로 설정하세요. 최상위 model 필드는 여전히 의미가 있습니다 — 첫 시도입니다 — 하지만 체인이 있으면 OrcaRouter는 체인을 우선합니다. 
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "models": ["openai/gpt-4o", "anthropic/claude-haiku-4.5", "google/gemini-2.5-pro"],
        "route": "fallback",
    },
)

​
규칙

  • 체인에 최대 5 모델. 초과분은 조용히 잘립니다.
  • 권장: 체인의 모든 모델은 동일한 엔드포인트 타입(모두 chat 또는 모두 image)이어야 합니다. 채팅 모델과 이미지 모델을 섞어도 게이트웨이가 크래시되지는 않지만, 실제로 요청을 처리하는 폴백은 호출한 엔드포인트와 일치해야 합니다(예: /v1/chat/completions를 호출하면 체인의 채팅 모델만 사용 가능).
  • 폴백 동작:
    • 해결할 수 없는 orcarouter/{name} 항목(잘못된 이름, 비활성화된 라우터)은 조용히 건너뜁니다.
    • 호출 키가 접근할 수 없는 모델(모델 허용 목록 불일치)은 조용히 건너뜁니다.
    • 주 모델이 업스트림에서 실패하면(5xx / 429 / 네트워크 오류) 다음 체인 항목이 시도됩니다.
    • 요청은 모든 체인 항목이 소진되었을 때만 실패합니다.
    • 스트리밍 주의: 응답의 첫 바이트라도 클라이언트로 전송되면 더 이상 폴백이 발동할 수 없습니다 — 업스트림이 스트림 중간에 끊기면 클라이언트는 잘린 스트림을 보게 되며, 다음 모델로의 투명한 재시도가 일어나지 않습니다.
  • 청구는 응답을 실제로 처리한 모델의 요율로 발생합니다 — 주 모델 요율이 아닙니다.
  • extra_body.route는 체인이 활성화되려면 정확히 "fallback"이 어야 합니다. 다른 값(또는 누락)은 체인이 무시되고 최상위 model만 사용됩니다.

​
어느 모델이 응답을 처리했는지 알기

X-Orca-Fallback-Level과 X-Orca-Fallback-Model 응답 헤더를 확인하세요. 응답 헤더 참조. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary"는 level 0; 그렇지 않으면 폴백 모델 이름

​
사용하지 말아야 할 때

체인을 작성하지 않고 OrcaRouter가 자동으로 가장 저렴한 사용 가능 모델을 선택하기를 원한다면 orcarouter/auto를 사용하세요. 폴백 체인은 순서를 명시적으로 제어하고 싶은 경우를 위한 것입니다.