Videos
Multi-scene videos
Your character acts the script out across several scenes — walking, showing, doing — instead of one static talking head. Same face and voice throughout, delivered as one continuous vertical video.
What you get
In multi-scene mode your character acts the script out across several scenes — we choose the locations, actions, and camera moves, keeping the same character throughout. You get one continuous 720p vertical video with seamless speech.
Reach for it when a static presenter isn't enough: behind-the-scenes tours, day-in-the-life content, product-in-hand demos, storytelling ads. For a straight to-camera update, talking-head is faster and cheaper.
The request
Same endpoint as talking-head, with mode: "scenes". This mode requires voice_id + script — the dialogue text drives the per-scene beats, so audio_url is rejected. captions and resolution are ignored (always 720p vertical).
| Field | Type | Description |
|---|---|---|
| mode | "scenes" required | Multi-scene mode. |
| character_id | uuid required | Who stars in the video. |
| voice_id | string required | The voice that speaks the script. |
| script | string required | Spoken verbatim across the scenes. Must estimate ≤ 60.5s of narration. |
| video_idea | string ≤2000 | The video's intent ("a barista giving a behind-the-scenes tour of the roastery"). Strongly recommended. |
| narration_mode | "auto" | "voiceover" | auto (default): decides per scene whether the character speaks on camera or narrates over action. voiceover: force narration everywhere — safest for languages or pacing where on-camera mouths must never be wrong. |
| scene_elements | array ≤6 | Real stills woven into the video: { "url", "role", "caption" } with role setting | product | prop. Your actual shopfront, your actual product — scenes are staged around them. |
| fast | boolean | Fast tier — lower latency, ~25% cheaper per second, slightly lower quality. Default false. |
| topic / audience / language | strings | Optional context — what the video is about, who it is for, and the spoken language. |
The 60.5-second cap
A script estimated over 60.5s of narration is rejected with 400 at queue time — nothing charged, no job started. Most scripts of ~150 words fit comfortably.
What it costs
Billed per second of finished video: the first scene is at the standard rate and every later scene at a lower rate (~0.6×), plus speech synthesis for the script.
| Tier | First scene | Later scenes | A real 20.7s video |
|---|---|---|---|
| Standard (default) | 31 credits/s | 19 credits/s | 561 credits (measured) |
| Fast | 24 credits/s | 15 credits/s | ~430 credits |
As always: estimate reserved at queue, measured actual settled on completion, over-reserve refunded. Get the exact quote first with POST /videos/estimate (same body, free) so you can show your user the price before committing.
Full example — every param populated
curl -X POST https://platform.promoat.ai/api/partner/v1/videos \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "scenes",
"character_id": "CHARACTER_ID",
"voice_id": "VOICE_ID",
"script": "Ever wondered how we roast our beans? Come on, I will show you. This is where every batch starts — green, dense, and full of potential.",
"video_idea": "a barista giving a behind-the-scenes tour of a small coffee roastery",
"narration_mode": "auto",
"scene_elements": [
{ "url": "https://your-cdn.com/shots/storefront.jpg", "role": "setting", "caption": "our shopfront" },
{ "url": "https://your-cdn.com/products/retail-bag.jpg", "role": "product", "caption": "the retail bag" },
{ "url": "https://your-cdn.com/props/scoop.jpg", "role": "prop", "caption": "the roasting scoop" }
],
"fast": false,
"topic": "specialty coffee roasting",
"audience": "local coffee lovers",
"language": "english"
}'
# → { "workflow_id": "partner_scn_1783…", "status": "queued", "credits_reserved": 620 }curl https://platform.promoat.ai/api/partner/v1/jobs/partner_scn_1783…/status \
-H "Authorization: Bearer $PROMOAT_KEY"
# → { "status": "completed",
# "video_url": "https://…/video.mp4", # one continuous 720×1280 video
# "credits_consumed": 561, … }Multi-scene jobs run longer than talking-head — more scenes means more render time. Budget 10–20 minutes and poll accordingly (job phases let you show progress meanwhile).