Skip to main content
POST
generate video

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-video, image-to-video, video-to-video, ingredients-to-video. 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 video. 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-video and video-to-video; every ref on ingredients-to-video. 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.

end_ref
string

End-frame image (models with supports_end_frame): the model interpolates from the start frame to it.

keyframe_refs
string[]

Images the video passes through between its start and end frames, in order (image-to-video on models with max_keyframes).

shots
object[]

Multi-shot on models with multi_shot_format structured. Prose models take the breakdown in the prompt.

characters
object[]

Characters held consistent, on models with max_characters, cited @Element1, @Element2 in the order given. Caps and lengths are in list_models.

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[]