Fallback моделей

Fallback моделей позволяет одному /v1/chat/completions запросу передать упорядоченный список моделей-кандидатов. GonkaGate сначала пробует первый подходящий кандидат, а затем переходит к следующему только если ошибку безопасно повторить.

Используйте это, когда одна модель предпочтительна, но приложению лучше получить ответ от резервной модели, чем упасть из-за временной проблемы модели или runtime.

Как это работает

Отправьте model, models или оба поля:

{
  "model": "moonshotai/kimi-k2.6",
  "models": ["minimaxai/minimax-m2.7"],
  "messages": [
    {
      "role": "user",
      "content": "Write a two sentence release note for a fallback model feature."
    }
  ]
}

Порядок кандидатов:

1. model, если поле передано.
2. Каждый элемент models по порядку.
3. Дубликаты схлопываются после нормализации.

Внутри каждая upstream-попытка всё равно использует одну model. Массив models остаётся request-level входом для роутинга, а не отправляется upstream как multi-model payload.

Формы запроса

Основная модель с резервными

Используйте этот вариант для большей части production-трафика. Запрос остаётся читаемым, а основная модель очевидна.

{
  "model": "moonshotai/kimi-k2.6",
  "models": ["minimaxai/minimax-m2.7"],
  "messages": [{ "role": "user", "content": "Summarize this incident." }]
}

Только список models

Если model не передана, первый элемент models становится основным кандидатом.

{
  "models": ["moonshotai/kimi-k2.6", "minimaxai/minimax-m2.7"],
  "messages": [{ "role": "user", "content": "Draft a short customer update." }]
}

Запрос с одной моделью

Существующие запросы продолжают работать. Fallback не включается, если нет models и если порядок моделей не приходит из пресета.

{
  "model": "moonshotai/kimi-k2.6",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

Поведение fallback

GonkaGate может попробовать следующий кандидат только до того, как зафиксировал видимый для клиента ответ.

Retry-eligible ошибки — это временные проблемы модели или runtime, например недоступный backend модели или transient upstream/runtime error. Это не общий механизм восстановления от любых ошибок.

Стоимость

Стоимость считается по модели, которая фактически завершила запрос.

• Response model и usage относятся к выбранному кандидату.
• В Dashboard usage и billing нужно смотреть по выбранной модели, а не только по первому значению model из запроса.
• Если все кандидаты упали до успешного completion, последняя fallback-модель не тарифицируется как успешная генерация.

Перед rollout используйте Get Models или живой каталог моделей, чтобы каждый candidate ID существовал для вашего ключа.

Использование с плагинами

Плагины резолвятся один раз для логического запроса, затем выбранная model attempt использует подготовленный request.

{
  "model": "moonshotai/kimi-k2.6",
  "models": ["minimaxai/minimax-m2.7"],
  "plugins": [
    {
      "id": "web",
      "max_results": 5
    }
  ],
  "messages": [{ "role": "user", "content": "What changed in today's release notes?" }]
}

Учитывайте правила:

• web, response-healing и privacy-sanitization применяются ко всему запросу.
• PDF Inputs проверяет capability моделей из fallback-кандидатов, когда запрошено native PDF forwarding.
• Ошибка конфигурации плагина не повторяется на следующей модели. Сначала исправьте payload плагина.

Использование с пресетами

Пресеты могут либо задавать порядок моделей, либо только добавлять общие defaults.

{
  "model": "moonshotai/kimi-k2.6",
  "models": ["minimaxai/minimax-m2.7"],
  "preset": "support-agent",
  "messages": [{ "role": "user", "content": "Reply to this support ticket." }]
}

С model плюс models плюс preset порядок fallback задаёт сам запрос, а пресет добавляет поддерживаемые defaults: prompt, параметры и reasoning.

Чтобы пресет задавал и порядок моделей, используйте пресет как модель:

{
  "model": "@preset/support-agent",
  "messages": [{ "role": "user", "content": "Reply to this support ticket." }]
}

См. Пресеты для Chat Completions для правил merge, slug-валидации и списков моделей, управляемых пресетом.

Использование с OpenAI SDK

Raw HTTP body — источник истины. Некоторые SDK не типизируют models как обычное поле, поэтому при необходимости передавайте его как extra body field.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gonkagate.com/v1",
    api_key="gp-your-api-key",
)

completion = client.chat.completions.create(
    model="moonshotai/kimi-k2.6",
    messages=[
        {"role": "user", "content": "Write a two sentence release note."}
    ],
    extra_body={
        "models": [
            "minimaxai/minimax-m2.7",
        ]
    },
)

print(completion.choices[0].message.content)

Для TypeScript обычный fetch — самый короткий полностью типизированный вариант:

const response = await fetch("https://api.gonkagate.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GONKAGATE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "moonshotai/kimi-k2.6",
    models: ["minimaxai/minimax-m2.7"],
    messages: [{ role: "user", content: "Write a two sentence release note." }]
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const completion = await response.json();
console.log(completion.choices[0]?.message?.content);

Лимиты и неподдерживаемые поля

• models должен быть непустым массивом, если поле передано.
• Каждый элемент models должен быть непустой строкой.
• models принимает до 64 элементов.
• Запрос должен содержать model или models.
• Используйте model IDs из GET /v1/models; не угадывайте ID по display name.
• GonkaGate не поддерживает provider, route, allow_fallbacks, provider ordering или provider filters в этом контракте.
• Эта страница описывает прямые /v1/chat/completions запросы. Chat history routes используют свой контракт model | models.

Диагностика

См. также

• Справочник Chat Completions API для точной схемы запроса.
• Гайд по выбору моделей для выбора актуальных model IDs.
• Пресеты для Chat Completions для сохранённого порядка моделей и общих defaults.
• Выбор плагина для runtime-расширений на уровне запроса.