Start here

What's new in 1.1

Sharper videos for less, scene-by-scene editing, studio voices, safe retries and a code on every error. Each card below opens the full guide with a request you can copy.

Videos

Talking-head videosVoiced from a script or your recording, at 480P, 768P (default) or 1080P. A 15 s video is 125 credits.POST /videos mode: talking_head Scene videosThe character acts the script out across clips — voiced, text-only or silent (5–60 s).POST /videos mode: scenes Scene photos with rolesUp to 3 photos of your real setting, product or prop, woven into the video.scene_photos[{ url, role, caption }]Scene planSplit a script into clip lines before you pay for anything. Free.POST /videos/scene-plan First frameIterate on the opening still for 4 credits, then animate exactly that frame.POST /images/first-frame kind Job statusA phase label, a progress percentage and a poster image while the video renders.GET /jobs/{id}/status

Edit a finished video

Every edit makes a new video and leaves the original untouched.

Scenes viewEvery scene of a finished video: its line, timing and clip.GET /videos/{id}/scenes Fix a sceneA new take, or a new frame from a description, for one scene.POST /videos/{id}/fix-scene Edit the scriptRewrite up to 20 lines; only those scenes are made again.POST /videos/{id}/edit-script Fix the soundA new take: free swap when it fits a scene video with no on-camera talking, otherwise a quoted remake. Use dry_run + expected_credits.POST /videos/{id}/fix-sound

Voices, speech and characters

Voice clonesYour first clone is free; later clones 30 credits.POST /voices sample_urls Studio voicesEight multilingual studio voices, free.GET /voices/presets Re-clone & deleteReplace an expired clone (free) or free a slot.POST /voices/{id}/reclone Text-to-speechThe new voice model, a language hint, and the characters billed.POST /tts CharactersGender and head covering on every character, kept consistent in video.POST /characters Regenerate a characterA new sheet for the same person, with an optional tweak.POST /characters/{id}/regenerate

Retries, prices and errors

Idempotency keysRetry any video call safely: same key, same job, charged once.Idempotency-Key header Price lockSend the quote back; if the price rose, nothing is queued.expected_credits Error codesEvery error carries error, error_code and message (all endpoints since 1.1.1).{ error, error_code, message }WarningsA successful call tells you what it adjusted, instead of failing.warnings[{ field, code, message }]PricingPer-second video rates by resolution, every line explained.price_table_version 2026-09-30 The $19.99 packThe default credit purchase: 1,499 credits on the current tier.Dashboard → Billing

Upgrade in four changes

Existing requests keep working. To get the most out of 1.1:

Quote first, then lock it. POST /videos/estimate with your body, then send expected_credits on POST /videos.
Send an Idempotency-Key on every video call, so a timeout is safe to retry.
Branch on error_code, not on the error text.
Show phase and progress from the status endpoint, and the poster_url once it appears.

All four in one request

curl -X POST https://platform.promoat.ai/api/partner/v1/videos \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4812-video-1" \
  -d '{
    "mode": "talking_head",
    "character_id": "CHARACTER_ID",
    "audio_url": "https://your-cdn.com/audio/15-second-take.mp3",
    "video_idea": "standing in a bright modern kitchen, smiling at the camera",
    "resolution": "768P",
    "expected_credits": 125
  }'

# 200 → { "workflow_id": "partner_h3t_…", "status": "queued", "credits_reserved": 125,
#         "price_table_version": "2026-09-30", "warnings": [], "duplicate": false }
# 409 → { "error": "QUOTE_MISMATCH", "error_code": "QUOTE_MISMATCH", "code": "quote_mismatch",
#         "credits_quoted": … }

curl https://platform.promoat.ai/api/partner/v1/jobs/partner_h3t_…/status -H "Authorization: Bearer $PROMOAT_KEY"
# → { "status": "running", "phase": "generating", "progress": 40, "poster_url": null, … }

Prices at a glance

What	Credits
Talking head, per second (768P)	8 / s
Scene video, per second (768P, reference / text)	8 / s · 4 / s
15 s talking head, 768P, your audio	125
15 s scene video, 768P, 2 scene photos	131
Character (create)	free
Character regenerate, first frame	4
Voice clone (first / later)	free / 30
Studio voice, estimate, scene plan, scenes view	free

Full table and worked examples in Credits & pricing; every detail of the release in the changelog.

← PreviousOverview & quickstart Next →Authentication