Videos

Scene videos

Your character acts the script out across several clips — walking, showing, doing — instead of one static talking head. Same face throughout, delivered as one continuous vertical video, with a voice or silent.

What you get

With mode: "scenes" (alias moving_scene) your character acts across several clips, merged into one 9:16 video. Three ways to run it:

For a straight to-camera update, talking head is simpler.

The request

Same endpoint and shared fields as talking head (character_id, voice_id + script or audio_url — recordings are now allowed on scenes — resolution, language, voice_settings, expected_credits, client_request_id). Scene-specific fields:

Scene photos and roles

Scene photos put your real place, product or prop into the video (reference mode only). Each one can say what it is; leave role out and we label it for you.

• Up to 3 photos are used. More → the first 3, with a SCENE_PHOTOS_TRUNCATED warning.
• A photo we can't fetch safely while the job runs is dropped, not fatal: the job continues, carries a SCENE_PHOTO_DROPPED warning (field scene_photos[i]), and is re-priced with the photos actually used — never above the reserve.
• Public https URLs of still images (JPEG, PNG, WebP, GIF or HEIC). Text mode ignores them, with a warning.

Plan the clips first (free)

Instant and free. Splits a script into clip lines you can show, edit, and send back as scene_lines.

curl -X POST https://platform.promoat.ai/api/partner/v1/videos/scene-plan \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "scenes",
    "script": "Ever wondered how we roast our beans? Come on, I will show you.",
    "language": "en"
  }'

{
  "scenes": [
    { "index": 0, "line": "Ever wondered how we roast our beans?", "seconds": 3.1 },
    { "index": 1, "line": "Come on, I will show you.", "seconds": 2.2 }
  ],
  "max_words_per_scene": 33
}

Errors: 400 INVALID_BODY, INVALID_SCRIPT, INVALID_DURATION, INVALID_VOICE_MODE.

Limits

What it costs

Per second of output, by resolution:

Worked examples, 15 s at 768P:

With voice_id + script a tts line is added and the length is estimated with headroom; you pay the lower of the reserve and the measured price. Get the exact quote with POST /videos/estimate (same body, free).

Full example

curl -X POST https://platform.promoat.ai/api/partner/v1/videos \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: roastery-tour-v1" \
  -d '{
    "mode": "scenes",
    "character_id": "CHARACTER_ID",
    "audio_url": "https://your-cdn.com/audio/roastery-15s.mp3",
    "video_idea": "a barista giving a behind-the-scenes tour of a small coffee roastery",
    "video_mode": "reference",
    "scene_photos": [
      { "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" }
    ],
    "scene_prompt": "warm morning light, handheld feel",
    "resolution": "768P",
    "language": "en",
    "expected_credits": 131
  }'

# → { "workflow_id": "partner_h3v_…", "status": "queued", "credits_reserved": 131,
#     "credits_quoted": 131, "job_type": "multi_scene_video", "resolution": "768P",
#     "price_table_version": "2026-09-30", "warnings": [], "duplicate": false }

{
  "mode": "scenes",
  "character_id": "CHARACTER_ID",
  "voice_mode": "none",
  "target_seconds": 15,
  "video_idea": "a slow morning in the roastery, beans pouring, steam rising"
}

Scene jobs take longer than talking heads — budget about 25 minutes and show phase / progress from the status endpoint meanwhile. Fix a single clip afterwards with Video edits.

Try it