Skip to main content
POST
generate image

Authorizations

Authorization
string
header
required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key
string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id
string

The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.

Body

application/json
type
string
required

One of text-to-image, image-to-image, ingredients-to-image. Which a given model accepts is in list_models types.

prompt
string
required

The prompt, in full.

idempotency_key
string
required

Idempotency key (a UUID). A retry with the same key returns the job already dispatched instead of charging again; a new attempt takes a new key.

Required string length: 1 - 200
model
string

A model id from list_models type image. Omitted: the account default.

settings
object

Per-model settings (validated against list_models).

source_refs
string[]

The media the model works from. Only the first ref is used on image-to-image; every ref on ingredients-to-image. Further images go in reference_refs.

reference_refs
string[]

Reference items: images for style or character consistency, videos for motion or style where list_models allows. Audio goes in settings.audioInputs as { url: an audio item ref }.

edit_points
object[]

Change specific spots and keep the rest, on models with supports_edit_points; the first source_ref is the media. Points are fractions from inspect_media with grid: true (frame mode for video). The prompt may be empty or describe the whole edit. On an image reference_refs follow the source and a marked copy (none on GPT Image 2.6). Aspect ratio and duration are kept.

Required array length: 1 - 8 elements
timeline_id
string

With clip_id: the first source_ref is that clip's media, only the part the clip plays is sent (and priced), and the result replaces the clip when ready, its place and look kept.

clip_id
string

With timeline_id: the clip to edit and replace.

folder
string

Folder path or id for the output; it must exist (organize_items create_folders). Omitted: the workspace generations folder.

mask_ref
string

A masked edit (image-to-image on models with supports_mask): a PNG item the size of the source, transparent where the model repaints, opaque where it keeps. The prompt says what goes in the painted region.

context
string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

ok
any
required
data
object
required
meta
object
required
media
object[]