openai/gpt-5.2:nitro. There are two kinds, and they behave differently in the Models API. Clients that resolve model metadata from the requested model ID, including SDKs, coding agents, and model pickers, need to handle both.
- Catalog variants are separate entries in
GET /api/v1/modelswith their own metadata. Only the models that list them support them. - Routing variants are accepted on any model ID at request time. They are not listed in
GET /api/v1/modelsand change only how the request is routed. The model’s metadata is the base model’s.
GET /api/v1/models is a catalog of models and catalog variants. It is not an exhaustive list of every model string a request can use. openai/gpt-5.2:nitro is a valid request model even though no entry with that id exists.Catalog variants
A catalog variant is a distinct entry in the models API. Itsid carries the suffix, and its pricing, context_length, supported_parameters, and endpoints describe that entry and can differ from the base model. For example, a :free entry can have a shorter context window than its base model, and its pricing is zero.
Sending a catalog suffix on a model that has no such entry does not fall back to the base model. The single-model lookup returns
404, the endpoint lookup returns 200 with an empty endpoints array, and inference requests fail because there is no endpoint to route to.
Routing variants
A routing variant is accepted on every model ID and is never an entry in the models API. It changes provider ordering or eligibility for the request, and nothing else about the model. Context length, capabilities, supported parameters, and the base per-token price all come from the base model’s entry.
Because
:nitro and :floor can select a service tier endpoint, the price actually charged for a request can differ from the base entry’s pricing. The response reports the tier that served the request, as described in Service Tiers.
Combining suffixes
Suffixes can be combined in any order, separated by colons. A model ID carries at most one catalog variant and any number of routing variants.:nitro, :floor, :exacto), the last one in the ID determines the sort.
Only the suffixes listed on this page are variants. Do not rely on any other suffix.
Resolving a model ID to its catalog entry
Send the model ID exactly as the user wrote it in the requestmodel field, and resolve metadata separately. The rule is:
- Split the ID on
:. The first segment is the base slug. - Keep the catalog variant if one is present (
:free,:batch,:thinking,:extended). Drop every routing variant (:nitro,:floor,:exacto,:online). - The result is the
idof the catalog entry to read metadata from.
:free resolves to the paid entry, which can report a larger context window and non-zero pricing, neither of which describes the free entry that serves the request.
Letting the API resolve it
The single-model and endpoint lookup routes accept any suffix and apply this rule server-side, so a client can pass the requested ID through unchanged::free on a model with no free entry, the single-model route returns 404 and the endpoints route returns 200 with "endpoints": []. Treat either as an unavailable model, not as a signal to retry with the base slug.
Offering routing variants in a model picker
Because routing variants are not in the catalog, a picker built fromGET /api/v1/models will not show them. To make them selectable, derive them from the base entries. Every model entry accepts :nitro, :floor, and :exacto, and the picker can present them as options on the base model while continuing to read metadata from the base entry. GET /api/v1/models/{author}/{slug}/endpoints lists the providers the sort will apply to.