Model routing and selection

Explicit model IDs must pass platform validation. Metadata filters narrow eligible candidates, while provider availability and run outcomes determine whether generation succeeds.

Model selection failures

First, distinguish an ID rejected by policy. If the send explicitly names invalid/model-xyz, the gateway refuses it with HTTP 403 and a message carrying model_access/MODEL_NOT_ALLOWED and the disallowed ID. Both send-message and send-message-sync perform this check before dispatching to the conversation. Correct every disallowed ID in the supplied primary/fallback list; adding an allowed fallback does not rescue the request.

Then distinguish a metadata-filter rejection. An allowed ID can still be absent from the resolved catalog or fail the required capability/price filter. When resolution succeeds but returns no eligible candidates, conversation preparation reports MODEL_FILTERED_OUT.

A later generation failure needs different recovery

If metadata resolution itself fails, preparation can continue without that validation and leave checking to the provider path. A later selection failure can use ERROR_CODE_MODEL_INVALID with reason ALL_MODELS_FILTERED and per-model reasons in its message. Follow the accepted run’s outcome; do not treat this as the earlier gateway rejection.

Filter precedence

Situation	Behaviour
No modelRoutingFilter set	No metadata filtering. Model-ID validation still runs.
Filter set, all fields zero/unset	No filtering — the same as not setting one
Filter on overrideGenerationConfig	Applies to that message only; the next message reverts to the thread default
A single model, no models array	The filter applies to that one model. If it fails, you get an immediate error.
model plus models	The filter applies to the merged candidate list — model first, then models

Allowed models

The platform accepts a curated allowlist. Everything else on this page filters within this set; a model offered elsewhere is not automatically accepted here.

For an explicit model choice, use these currently accepted model-ID patterns:

Pattern	Current validation behavior
google/gemini*	Prefix accepted without requiring a hyphen after gemini, except google/gemini-2*
deepseek/*	Provider prefix accepted
z-ai/*	Provider prefix accepted
anthropic/claude-sonnet-5, anthropic/claude-sonnet-4.6	Exact IDs accepted
openai/gpt-6-luna, openai/gpt-6-luna-pro, openai/gpt-6-sol, openai/gpt-6-sol-pro	Exact IDs accepted; other openai/* IDs are rejected

This is input validation, not a live provider catalog. A newly named model can pass the prefix check and still be unavailable, incompatible with your region/account or unsupported for the requested operation. Confirm actual model availability, capabilities, licensing and data handling before enabling it. Do not infer prices or "best" models from family names.

An explicitly disallowed model — in model or any entry of models — rejects the request:

{
  "code": 403,
  "message": "[403] policy denied (suspension_state=NONE): model_access/MODEL_NOT_ALLOWED: model \"openai/gpt-5\" is not allowed"
}

Match on the MODEL_NOT_ALLOWED token and the ID quoted after it; see model errors.

The same allowlist applies when storing a per-user default via update-generation-config.

Candidate resolution and fallback

You can give the platform several candidate models instead of one, and constrain which of them may be used. Explicit model IDs are validated before generation starts. When candidate metadata is available, capability and price filters narrow that list during preparation. A metadata lookup failure can leave those checks to the later generation path; an accepted request is not proof that every constraint was checked.

Set models for a fallback chain, and modelRoutingFilter to require capabilities — a minimum context window, image input or a per-token price filter. Candidates that fail are dropped; generation proceeds with whatever survives. If a successful metadata lookup leaves no eligible candidates, the request is rejected before generation. Follow an accepted run to its outcome for failures discovered later.

Setting no filter is a valid choice and changes nothing about how a thread behaves.

Available models

Set model — or the models fallback list — to a model from the platform allowlist. The canonical list, with the exact rejection error and the rule for model variant suffixes, lives in Allowed model patterns.

The platform accepts a curated set. Requesting a model outside it fails immediately with 403 and MODEL_NOT_ALLOWED. See Model Routing & Pre-Filter for capability-based filtering within that set.