Skip to main content
POST
Compose Narrated Video
Compose a narrated, multi-shot video from a script — not a single ~5s clip. Lamina synthesizes the narration, storyboards it into beats, generates a continuity-chained shot per beat, and renders with transitions, Ken-Burns, and captions. The operation is asynchronous — composition takes minutes. You get a runId immediately; poll Get Compose Run for stage progress and the final video URL. Steer the render through the script, never models: optional direction (free text) and sections (per-span hints). Pass an idempotencyKey to make retries safe — a repeated key returns the same run, so you never double-charge. Invalid input returns a 400 whose details.reason is machine-readable (SCRIPT_TOO_LONG, MISSING_REQUIRED_INPUT, …) so an agent can self-correct.

Authorizations

x-api-key
string
header
required

Workspace API key. Prefix: lma_. Example: lma_abc123...

Body

application/json

Shared input for POST /v1/compose/plan and POST /v1/compose/video. The user picks a format (never a model) and steers the render via the scriptdirection + sections — not by naming models.

script
string
required

The narration to speak (a hook + one insight + a CTA). Its spoken length must be ≤ the maxScriptDurationSec capability (~90s).

Maximum string length: 4000
title
string

Video title.

generationBrief
string

One-paragraph visual brief for the shots.

format
string

A format id from GET /v1/compose/formats. Omit to auto-route the script to the best available format.

direction
string

Free-text creative direction ("open on the product, fast cuts, end on the logo") — steers the render without naming models.

sections
object[]

Structured per-span storyboard hints, for a prescriptive caller.

inputs
object

A format's required inputs, keyed by input key (e.g. a presenterImage key mapping to an https URL). See each format's inputs in GET /v1/compose/formats.

aspectRatio
enum<string>
default:16:9
Available options:
16:9,
9:16,
1:1,
4:5,
4:3
voiceId
string

ElevenLabs voice id for the narration. Omit for the default voice. (compose/video only.)

clipSeconds
integer

Target per-clip length within the capability window.

idempotencyKey
string

Dedupe retries — a repeated key returns the same run (no double charge). (compose/video only.)

Response

Composition started. Poll the run for progress + results.

data
object