Model tiers

Some models are offered in more than one tier. A tier is the same model sold at a different price, for example a lower-cost tier next to the Default one. One API key reaches every tier; you choose a tier by the model name, not by a separate key or setting.

Default tier

The plain model name always uses the Default tier. Existing requests keep working unchanged when a model gains another tier.

{ "model": "gpt-image-2" }

Choose a tier

Append a colon and the tier ID to the model name:

{ "model": "gpt-image-2:<tier>" }

This works for text, image, video and audio models, wherever the request names a model: the model field of a JSON body, the model form field of an audio upload, and the model segment of a Gemini native path. In a Gemini path the action stays last:

POST /v1beta/models/<model>:<tier>:generateContent

Find the tiers of a model

• On each model page, a tier switch above the price table shows each tier's prices and the model ID to call. Pages with a single price list the tiers in a Price tiers table instead. Both appear only when the model has more than one tier.
• Each model's Markdown guide, /models/<page>/llms.txt, lists the complete prices of every tier.
• GET /v1/models lists <model>:<tier> next to <model> for every model that your key can call in more than one tier.

In the Playground of text models, the tier selector switches between the same tiers. The Playground of image, video and audio models uses the Default tier; call other tiers through the API.

Billing and behavior

• A tier request runs only in that tier and is billed at that tier's price.
• If the tier cannot serve the request, the request fails. It never switches to another tier, so it is never billed at a different price.
• Responses and task results report the plain model name.
• A key that was created for one tier only can call that tier and no other.

Errors

See Errors for the response shape.