Model Fallbacks

Use model fallbacks when your application has a preferred model but should still answer if that model is temporarily unavailable. Add backup model IDs to models; GonkaGate tries the candidates in order and returns the first successful /v1/chat/completions response.

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

Before production rollout, refresh each candidate from Get Models. Use exact model IDs, not display names.

Choose Your Request Shape

Preferred Model With Backups

Use model for the first choice and models for backups. This keeps the main model easy to see in code and logs.

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

Backup List Only

You can omit model. In that case, the first models entry is tried first.

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

One Model, No Fallback

Existing OpenAI-compatible requests keep working. Fallback is active only when you send models or use a preset that provides a model list.

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

Candidate Order

GonkaGate builds the candidate list from:

1. model, when present.
2. Each entry in models, in order.
3. The same model ID only once, if it appears more than once.

The response is still a normal chat completion from one selected model. models tells GonkaGate what to try; it is not a multi-model prompt sent to a provider.

When Fallback Can Happen

Fallbacks are for temporary model or runtime failures before the response starts. They do not fix invalid requests, account problems, or plugin configuration errors.

Billing

Billing follows the model that actually completes the request.

• The returned completion and usage belong to the selected candidate.
• Dashboard usage should be read by the selected model, not only by the first model value you sent.
• If every candidate fails before a completion is produced, there is no completed fallback generation to bill.

Use With Plugins

Send plugin settings the same way you do for a single-model 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?" }
  ]
}

Keep these rules in mind:

• web, response-healing, and privacy-sanitization apply to the whole request.
• PDF Inputs checks whether the fallback candidates can handle native PDF forwarding when you request it.
• A plugin configuration error is not retried on the next model. Fix the plugin settings first.

Use With Presets

If you send model, models, and preset together, your request controls the fallback order. The preset still adds supported defaults such as prompt, parameters, and reasoning.

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

To let the preset choose the model order, use the preset as the model:

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

See Chat Completion Presets for preset merge rules, slug validation, and preset-managed model lists.

Use With OpenAI SDK

Some OpenAI-compatible SDKs do not expose models as a typed field. Send it as an extra request body field when needed.

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)

For TypeScript, plain fetch is the smallest fully typed option:

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

Limits And Unsupported Fields

• Send at least one of model or models.
• When present, models must be a non-empty array.
• Each models item must be a non-empty string.
• models accepts up to 64 entries.
• Use model IDs from GET /v1/models; do not guess IDs from display names.
• GonkaGate does not support provider, route, allow_fallbacks, provider ordering, or provider filters in this request contract.
• This page covers direct /v1/chat/completions requests. Chat history endpoints use their own model | models behavior.

Troubleshooting

See Also

• Chat Completions API reference for the exact request schema.
• Model Selection Guide for choosing current model IDs.
• Chat Completion Presets for saved model order and shared settings.
• Choose Plugin for plugins that run with a request.