Videos

Talking-head videos

One continuous shot of your character presenting to camera — the workhorse format for updates, promos, and UGC-style ads. Up to 59 seconds, vertical, studio lipsync always on, ready to post.

How a job runs

POST /videos with mode: "talking_head" queues an async job and returns immediately. The workflow then: plans the shot from your video_idea (or takes your ready-made first frame) → gets the speech audio (synthesized from your script, or your uploaded audio) → renders the character speaking it → runs the studio lipsync pass (always — there's no tier to pick) → burns in captions if you asked for them. You poll the job until it hands you a video_url.

The request

Dynamic captions

Set use_dynamic_captions: true to burn in dynamic captions — big, bold captions that reveal word by word as your character speaks, with the key words popped in colour for emphasis. They render in a heavy weight on a solid background band, so they stay readable over any footage, and cover both Latin and Arabic scripts (pass captions_language: "ar" for Arabic). Flat 10 credits, quoted and charged like every other line item.

The 59-second cap

What it costs

Line items sum: render seconds × rate, the always-on studio lipsync at ~13.4/s, plus speech synthesis (when using a script), a first frame (when the job generates one), and captions if chosen. Two worked examples for a 30-second script:

Don't do this math yourself — POST /videos/estimate quotes any request exactly, for free, before you commit. The exact estimate is reserved at queue time (credits_reserved) and settles to the measured actual on completion — how billing settles.

Quote it, then queue it

curl -X POST https://platform.promoat.ai/api/partner/v1/videos/estimate \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "talking_head",
    "character_id": "CHARACTER_ID",
    "voice_id": "VOICE_ID",
    "script": "Hi! Three quick updates from the shop this week…",
    "video_idea": "standing in a bright modern kitchen, smiling at the camera",
    "resolution": "720p",
    "use_dynamic_captions": true
  }'

# → { "credits_required": 290, "credits_balance": 961, "sufficient_credits": true,
#     "estimated_seconds": 7.4,
#     "breakdown": { "render_credits": 111, "lipsync_credits": 99, "tts_credits": 10,
#                    "first_frame_credits": 6, "captions_credits": 10 } }

curl -X POST https://platform.promoat.ai/api/partner/v1/videos \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ...same body... }'

# → { "workflow_id": "partner_thv_1783…", "status": "queued", "credits_reserved": 290 }

curl https://platform.promoat.ai/api/partner/v1/jobs/partner_thv_1783…/status \
  -H "Authorization: Bearer $PROMOAT_KEY"

# → { "status": "completed",
#     "video_url": "https://…/final.mp4",
#     "credits_consumed": 284, … }

Typical wall-clock: 4–8 minutes for a 480p clip (the lipsync pass is part of every run). Up to 5 jobs can run at once (429 beyond that).

The other two audio/frame sources

Instead of voice_id + script, drop in pre-recorded audio; instead of video_idea, drop in a ready-made frame:

curl -X POST https://platform.promoat.ai/api/partner/v1/videos \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "talking_head",
    "character_id": "CHARACTER_ID",
    "audio_url": "https://your-cdn.com/audio/narration.mp3",
    "first_frame_url": "https://your-cdn.com/frames/opening-shot.jpg",
    "resolution": "720p",
    "use_dynamic_captions": true
  }'

Try it