Перейти к основному содержанию
OrcaRouter может последовательно пробовать несколько моделей, пока одна не сработает. Полезно для устойчивости (если один провайдер ограничивает запросы или недоступен) и для контроля стоимости (использовать более дешёвую модель и при необходимости переключаться на более мощную).

​
Как использовать

Поместите упорядоченный список идентификаторов моделей в extra_body.models и установите 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 моделей в цепочке. Лишние молча отбрасываются.
  • Рекомендация: все модели в цепочке должны быть одного типа эндпоинта (все чат-модели или все image-модели). Смешивание чат-модели с image-моделью не приведёт к падению шлюза, но резервная модель, которая фактически обслужит запрос, должна соответствовать вызванному вами эндпоинту (например, если вы вызвали /v1/chat/completions, в цепочке могут использоваться только чат-модели).
  • Поведение резервирования:
    • Неразрешимые записи orcarouter/{name} (неверное имя, отключённый маршрутизатор) молча пропускаются.
    • Модели, к которым у вызывающего ключа нет доступа (несоответствие allowlist моделей), молча пропускаются.
    • Когда основная модель отвечает ошибкой на стороне апстрима (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" means level 0; otherwise the fallback model name

​
Когда это не нужно

Если вы хотите, чтобы OrcaRouter автоматически выбирал самую дешёвую доступную модель без написания цепочки, используйте orcarouter/auto. Цепочки резервирования нужны, когда вы хотите явный контроль над порядком.