Create a Compose job | EmpirioLabs AI Docs

Starts a multi-step Compose video production. Use mode: "plan" to create an editable storyboard from a brief or script. Use mode: "render" with a storyboard to generate voiceover, visuals, captions, optional music, and the final MP4. Use mode: "edit" with a prior render manifest plus edits to rework selected scenes.

The endpoint is async and returns a job envelope immediately. Poll GET /v1/jobs/{job_id} until the job is terminal.

Starts a multi-step Compose video production. Use `mode: "plan"` to create an editable storyboard from a brief or script. Use `mode: "render"` with a storyboard to generate voiceover, visuals, captions, optional music, and the final MP4. Use `mode: "edit"` with a prior render manifest plus edits to rework selected scenes. The endpoint is async and returns a job envelope immediately. Poll `GET /v1/jobs/{job_id}` until the job is terminal.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Request

This endpoint expects an object.

recipestringRequired

Compose recipe slug from GET /v1/videos/compose/recipes.

modeenumRequiredDefaults to plan

briefstringOptional

Topic, product idea, or direction for mode: "plan".

scriptstringOptional

Optional script text for plan mode.

storyboardobjectOptional

Storyboard returned by plan mode and accepted by render mode.

manifestmap from strings to anyOptional

Prior render manifest for edit mode.

editslist of objectsOptional

Scene-level edit instructions for edit mode.

aspect_ratiostringOptional

scene_countintegerOptional1-12

caption_stylestringOptional

musicstringOptional

Optional music direction or preset.

voicestringOptional

Optional voice preset or voice ID for narration.

product_imagestringOptionalformat: "uri"

Optional product reference image (http(s) URL) for recipes that accept one. Pass a URL the service can fetch; this endpoint does not accept file uploads.

face_imagestringOptionalformat: "uri"

Optional presenter / face reference (http(s) URL) for recipes that require one (Talking Head, AI Avatar Explainer, etc.). Pass a URL the service can fetch; this endpoint does not accept file uploads.

character_image_urlstringOptionalformat: "uri"

Optional character reference frame (http(s) URL) for character recipes; it overrides the generated character. URL only, the API does not accept uploads.

gameplay_stylestringOptional

Optional gameplay background style when a recipe supports gameplay variants.

videostringOptionalformat: "uri"

For the Auto Captions recipe (recipe: "auto-captions"): the http(s) URL of the video to caption. Send a URL the service can fetch (for example a signed link or any publicly reachable URL). This endpoint does not accept multipart file uploads, so host the file and pass its URL. Aliases: video_url, input_video.

languagestringOptionalDefaults to auto

Auto Captions: the spoken language of the video, or auto to detect it.

translate_tostringOptional

Auto Captions (optional): a target language to add a translation line under each spoken caption. Omit or use none for the original language only.

speakersbooleanOptionalDefaults to true

Auto Captions: give each detected speaker its own caption color.

model_overridesmap from strings to stringsOptional

Optional per-stage model overrides. Values must be listed in the recipe’s model options.

script_modelstringOptional

Shortcut for model_overrides.script.

visual_modelstringOptional

Shortcut for model_overrides.visual.

image_modelstringOptional

Shortcut for model_overrides.image.

voice_modelstringOptional

Shortcut for model_overrides.voice.

music_modelstringOptional

Shortcut for model_overrides.music.

Response

Compose job accepted. Poll the jobs endpoint for the result.

job_idstringOptional

statusenumOptional

poll_urlstringOptional

created_atdatetimeOptional

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error