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 key's own.

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

A key you mint per dispatch (a UUID). The same key on a retry 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, image-to-video and video-to-video; every ref on ingredients-to-* types. Further images go in reference_refs.

reference_refs
string[]

Reference items: images for style or character consistency, videos for motion or style on models that take them (list_models). Audio references go in settings.audioInputs.

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 a picture the marked copy is image 2, so reference_refs start at image 3. Shape and length 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 takes the clip's slot when it lands, 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[]