Create Image

Generate images from text, or guide them with input_references - one endpoint for every image model.

Generate an image from a text prompt, or guide the result with input_references for an edit or remix. The same call handles every image model - there is no separate endpoint to switch to for reference-guided requests.

POST /v1/images

Authentication

AuthorizationBearerrequired

API key as bearer token in the Authorization header. Create keys at Manage API Keys.

Headers

Content-Typestringrequired

Must be application/json.

Body

modelstringrequired

Image model id from GET /v1/models. Example: gpt-image-2, gpt-image-1-mini, gemini-3-pro-image.

promptstringrequired

Text description of the image to generate, or the instruction to apply to input_references.

input_referencesImageReference[]optional

Source images to guide the result. Each entry is { "type": "image_url", "image_url": { "url": "..." } }, where url is an https:// URL, a data: URL, or a file_id from POST /v1/files. Rejected for models that don't accept image input.

nintegeroptionalDefault 1

Number of images to generate. Some models only support 1.

aspect_ratiostringoptional

Output shape. Every image model takes a ratio, and each declares the ones it supports in architecture.image_aspect_ratios. auto leaves the choice to the model.

Allowed values:auto1:13:22:34:33:416:99:1621:9

qualitystringoptional

How much rendering effort the model spends. Declared per model in architecture.image_qualities.

Allowed values:autolowmediumhigh

resolutionstringoptional

Output detail expressed as a resolution step, for models that work this way. Declared per model in architecture.image_resolutions. A model offers quality or resolution, never both.

Allowed values:auto5121K2K4K

output_formatstringoptional

Output image format, where the model supports choosing one.

Allowed values:pngjpegwebp

output_compressionintegeroptional

Compression level (0-100) for jpeg or webp output.

userstringoptional

End-user identifier for abuse tracking.

Responses are always base64

Images come back as data[].b64_json, on every model. One output shape means the code that reads a result never has to branch on which model produced it.

The model catalogue decides, not the gateway

GET /v1/models reports each model's architecture.image_aspect_ratios, image_qualities and image_resolutions. A value outside those lists returns 400, and so does a knob the model doesn't offer - nothing is silently dropped or substituted, so a request that succeeds is a request the model actually honoured.

Response

idstringoptional

Gateway-assigned response identifier (avn_...). Used across logs, billing, and feedback.

createdintegeroptional

Unix timestamp (seconds) when the images were generated.

modelstringoptional

The model that generated the images.

dataImage[]optional

Array of generated images. Each contains b64_json, plus revised_prompt if the model rewrote your prompt.

sizestringoptional

Pixel dimensions of the result, when the model reports them.

usageobjectoptional

Token usage (input_tokens, output_tokens, total_tokens, plus input_tokens_details/output_tokens_details image vs. text breakdowns) for token-billed models. Models billed per image report all-zero usage plus an image_count.

Errors

All errors follow the OpenAI structured shape:

{ "error": { "type": "invalid_request_error", "message": "..." } }

Status	`error.type`	Meaning
`400`	`invalid_request_error`	Schema violation, unsupported parameter value, or content policy rejection.
`401`	`authentication_error`	Missing or invalid API key.
`402`	`billing_error`	Account out of credit or hit a spend limit.
`429`	`rate_limit_error`	RPM exceeded. Respect `Retry-After`.
`500`	`internal_server_error`	Unexpected gateway failure.