Models
The models the AI ops run on — what model may name on a job or a preset step, with each model's price, its categories and how big an image it is handed
1 endpoint under /api/v1/ai-models. What every call shares is on the REST overview, and what they are for — with the calls for every SDK, the CLI and MCP — on Ops & models → Models. * marks a required field.
List AI models
GET /api/v1/ai-models
Every model an AI op can run on, across the providers behind this API. A model runs an op when its categories include the op's modelCategory (GET /api/v1/ops); naming any other model is 400 invalid_param, with the models that fit in details.allowed. Leave model out and the op's defaultModel runs.
Each entry carries its price per image after markup (priceRange) beside the provider's own list price (providerPrice, providerPriceRange), the parameters it takes (params, in the op catalogue's shape), and maxInputEdge / maxInputImages — how big an input it is handed and how many images one call takes (what bounds a preset's reference images). The exact price of one request is the dry run.
The snake_case names, parameters, supported_parameters and created are deprecated and go on 2027-01-12 (https://imagestep.dev/docs/changelog#2026-10-14-model-fields): until then every answer carries both names, and Deprecation / Sunset / Link headers that say so.
USE THIS WHEN:
- Choosing a
modelfor an AI op, or checking one before a submit - Checking what a model costs, or how many reference images it takes
DO NOT USE WHEN:
- You want each op's default model and its price →
GET /api/v1/ops, which carries them
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| mode | query | string | ai_image (the default): the models the image ops run · analyze: the models the analyze op sells, priced per imageone of ai_image · analyze |
Returns 200 — data is ModelDTO[]
The models of that mode
Errors
| Status | Code and when |
|---|---|
| 400 |
|
Objects
Each described once; a linked type is another object on this page.
Deprecation
A model on its way out, and what replaces it
| Field | Type | Description |
|---|---|---|
| announced (required) | string | When the provider announced the retirement, an ISO datee.g. "2026-11-10" |
| changelog (required) | string | The changelog entry: what changes, how the parameters map, how the price movese.g. "https://imagestep.dev/docs/changelog#2026-11-10-gpt-image-2" |
| retireAt (required) | string | The day this service switches, 00:00 UTC, an ISO date: from then the id runs as successor, or is refused when there is nonee.g. "2027-02-09" |
| shutdown (required) | string | The day the provider stops serving it, an ISO datee.g. "2027-02-10" |
| successor | string | The model it runs as from retireAt, its parameters mapped; absent when it is refused from thene.g. "openai/gpt-image-2.6-flare" |
ModelDTO
A model an AI op can run on, with its price and what it accepts
| Field | Type | Description |
|---|---|---|
| categories | string[] | What the model is sold for. It runs an op when this includes the op's modelCategory (GET /api/v1/ops)e.g. ["image_generate","image_edit"] |
| completionPrice | string | Price per 1M output tokens in USDe.g. "15.00" |
| completion_price | string | Deprecated: completionPrice, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| contextLength | integer (int32) | Maximum context window supported by the model (tokens)e.g. 128000 |
| context_length | integer (int32) | Deprecated: contextLength, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| created | integer (int64) | Deprecated, and goes on 2027-01-12 with no replacement: it was never when the model changed, only a constant per provider. https://imagestep.dev/docs/changelog#2026-10-14-model-fieldse.g. 1711500000 |
| deprecation | Deprecation | Present while the model is being retired (apps/service/doc/models.md): when it was announced, the day this service switches, the provider's own shutdown, what it runs as from then — absent when it is refused from then — and the changelog entry. Absent for a model that is not going. A retired model is no longer listed; naming it runs its successor. |
| description | string | Short description of the model's capabilitiese.g. "Large multimodal model with fast responses." |
| id (required) | string | The model's id — what model names on a job or a preset stepe.g. "fal-ai/bria/background/remove" |
| imageRequired | boolean | Whether an input image is required (true), optional (false), or not supported (null)e.g. true |
| image_price_range | string | Deprecated: priceRange, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| image_required | boolean | Deprecated: imageRequired, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| inputModalities | string[] | Input modalities supported by the modele.g. ["text","image"] |
| input_modalities | string[] | Deprecated: inputModalities, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| maxInputEdge | integer (int32) | The longest edge, in pixels, of an input image this model is handed: a larger input is turned upright, scaled down to it and re-encoded as WebP with no metadata before the provider sees it. For a model billed per megapixel it is also what the quoted price assumes. Absent for a model that takes no image.e.g. 2048 |
| maxInputImages | integer (int32) | Maximum number of input images accepted. null = no image input, 1 = single image, >1 = multi-imagee.g. 1 |
| max_input_edge | integer (int32) | Deprecated: maxInputEdge, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| max_input_images | integer (int32) | Deprecated: maxInputImages, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| mode | string | Model mode: analyze for the models the analyze op sells, ai_image for the restone of ai_image · analyze |
| name | string | Human readable model namee.g. "OpenAI GPT-4o" |
| outputModalities | string[] | Output modalities supported by the modele.g. ["text","image"] |
| output_modalities | string[] | Deprecated: outputModalities, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| parameters | any | Deprecated: read params, the same declaration in the op catalogue's shape; goes on 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields. A list of {key, label, type, defaultValue}, with options or min / max where the value is bounded |
| params | object | What a job's parameters may carry on this model, in the op catalogue's shape (GET /api/v1/ops → params): name → {type, enum?, min?, max?, default?, title, description?}. A key not here, or a value outside its enum or bounds, is 400 invalid_param. Empty for an analyze model: its two parameters are the op's own |
| priceRange | string | Our price per image in USD — the provider's list price plus our markup — as one figure, or min - max across sizes, qualities or scale factorse.g. "$0.009 - $0.133" |
| promptPrice | string | Price per 1M input tokens in USDe.g. "5.00" |
| prompt_price | string | Deprecated: promptPrice, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| providerPrice | string | The provider's list price per image in USD, before our markup — the cheapest end when the price has a range. Every model carries one, so our multiple of it can be checked.e.g. "0.039" |
| providerPriceRange | string | The provider's list price range in USD across the same span as priceRange. Present only for models whose provider price depends on a parameter.e.g. "$0.12 - $0.48" |
| provider_price | string | Deprecated: providerPrice, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| provider_price_range | string | Deprecated: providerPriceRange, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| series | string | Provider family derived from the model id prefixe.g. "Openai" |
| structuredOutput | boolean | Whether the model supports JSON schema structured outpute.g. true |
| support_structured_output | boolean | Deprecated: structuredOutput, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
| supported_parameters | string[] | Deprecated: params' keys, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-model-fields |
Retiring and retired models
A provider retires its models on its own dates. From the day it announces one, the model is listed with deprecation and a request that runs it answers with a model_deprecated warning and a Deprecation header. On retireAt — the day before the provider stops — the id stops being listed and runs as its successor, its parameters mapped and at the successor's price, which a dry run quotes; with no successor it is 400 invalid_param. Each row is an entry on the changelog: the mapping, and how the price moves.
| model | announced | retireAt | provider shutdown | runs as |
|---|---|---|---|---|
| google/gemini-3-pro-image-preview | 2026-06-18 | 2026-06-24 | 2026-06-25 | google/gemini-3-pro-image |
| google/gemini-3.1-flash-image-preview | 2026-06-18 | 2026-06-24 | 2026-06-25 | google/gemini-3.1-flash-image |
| openai/gpt-image-2 | 2026-11-10 | 2027-02-09 | 2027-02-10 | openai/gpt-image-2.6-flare |
| openai/gpt-image-2-2026-04-21 | 2026-11-10 | 2027-02-09 | 2027-02-10 | openai/gpt-image-2.6-flare |