Резервные модели

Используйте резервные модели, когда у приложения есть основная модель, но ответ всё равно нужен, если она временно недоступна. Добавьте ID резервных моделей в models; GonkaGate попробует кандидатов по порядку и вернёт первый успешный ответ /v1/chat/completions.

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

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

Выберите форму запроса

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

Используйте model для первого выбора, а models для резервных моделей. Так основную модель проще увидеть в коде и логах.

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

Только список резервных моделей

Можно не передавать model. В этом случае первым будет попробован первый элемент models.

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

Одна модель без fallback

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

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

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

GonkaGate собирает список кандидатов так:

1. model, если поле передано.
2. Каждый элемент models по порядку.
3. Один и тот же model ID только один раз, даже если он повторился.

Ответ остаётся обычным chat completion от одной выбранной модели. models говорит GonkaGate, что пробовать; это не multi-model prompt для провайдера.

Когда fallback сработает

Fallback помогает при временных ошибках модели или runtime до начала ответа. Он не исправляет невалидный запрос, проблемы аккаунта или ошибки конфигурации плагинов.

Стоимость

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

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

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

Передавайте настройки плагинов так же, как для запроса с одной моделью.

{
  "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 проверяет, могут ли fallback-кандидаты обработать native PDF forwarding, когда вы его запрашиваете.
• Ошибка конфигурации плагина не повторяется на следующей модели. Сначала исправьте настройки плагина.

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

Если вы передаёте model, models и preset вместе, порядок fallback задаёт сам запрос. Пресет всё равно добавляет поддерживаемые общие настройки, например prompt, параметры и reasoning.

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

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

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

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

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

Некоторые OpenAI-совместимые SDK не типизируют models как обычное поле. При необходимости передавайте его как дополнительное поле тела запроса.

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);

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

• Передайте хотя бы одно поле: model или models.
• Если models передано, это должен быть непустой массив.
• Каждый элемент models должен быть непустой строкой.
• models принимает до 64 элементов.
• Используйте ID моделей из GET /v1/models; не угадывайте IDs по названиям из интерфейса.
• GonkaGate не поддерживает provider, route, allow_fallbacks, provider ordering или provider filters в этом контракте.
• Эта страница описывает прямые запросы /v1/chat/completions. Эндпоинты истории чата используют своё поведение model | models.

Диагностика

См. также

• Справочник Chat Completions API для точной схемы запроса.
• Гайд по выбору моделей для выбора актуальных ID моделей.
• Пресеты для Chat Completions для сохранённого порядка моделей и общих настроек.
• Выбор плагина для плагинов, которые выполняются вместе с запросом.