Skip to main content
POST

Overview

The dashboard’s Media Generator, from the API: one image from a prompt, made with the same models, styles and references, at the same price, and saved to your media library. The call answers 202 right away with the new mediaId; the image is generated after the response. Poll Get Media until status is COMPLETED (its url is the image) or FAILED, then use the id in any create endpoint.
  • model: an id of GET /v1/catalog/image-models. Defaults to gpt_image_2.
  • style: an id of GET /v1/catalog/visual-styles (your own custom-<id> styles included). Its look is added to the prompt; with no referenceMediaIds, a library style also sends its sample images as references, as in the dashboard.
  • referenceMediaIds: finished images of your library for the model to keep (a person, a product, a look), up to the model’s maxReferenceImages.
One image per call, as in the dashboard. It costs the model’s image price (usedCredits in the answer); teams on their own provider keys (BYOK) are not charged and need their OpenRouter key. If the generation fails the credits come back, and one still running after 60 minutes is given up on, reads as FAILED and is refunded too.
Poll Get Media every few seconds, or pass a webhook (with optional metadata) to be told once it is COMPLETED or FAILED: see media webhooks. An image usually takes a few seconds to a minute. A FAILED media says why in its error.

Errors

Every refusal below happens before anything is charged or created.
Animate the image next: pass its mediaId as imageMediaId to Generate Video.

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string

Makes the request safe to retry. 1-255 printable ASCII characters, one per operation (your job id, or a UUID you store), reused on every retry. Within 24 hours the same key with the same body answers with the first response and the header Idempotent-Replayed: true, without running or charging again. Keys are scoped to your team and the endpoint. 5xx answers and refusals before anything ran (401, 402, 403, 409, 429) are not kept. See Idempotency.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Body

application/json
prompt
string
required

What to generate.

Maximum string length: 5000
model
string
default:gpt_image_2

An id of GET /v1/catalog/image-models.

aspectRatio
enum<string>
default:ratio_9_16
Available options:
ratio_9_16,
ratio_1_1,
ratio_16_9
style
string

An id of GET /v1/catalog/visual-styles (your own custom-<id> included): its look is added to the prompt. Without referenceMediaIds, a library style also sends its sample images as references.

referenceMediaIds
string[]

Ids of finished images of your media library for the model to keep. At most the model's maxReferenceImages (400 above it, or when the model takes none).

name
string

Name in your library. Defaults to Generated Image - <date> / Generated Video - <date>.

Maximum string length: 255
webhook
string

Public https URL told once when the media is COMPLETED or FAILED (events media.completed / media.failed, signed like every Hooked webhook). See Webhooks.

Maximum string length: 500
metadata
object

Any JSON object of your own (max 5 KB). Sent back in the webhook payload.

Response

Generation started

success
boolean
message
string
data
object