Start here

What's new in 1.3

Credits now come from a weekly or monthly plan, at the Promoat app's prices, on the dashboard. Below that, the 1.1 tour: sharper videos for less, scene-by-scene editing, studio voices, safe retries and a code on every error. Each card opens the full guide.

Plans, new in 1.3

Requests and responses are unchanged. What changed is how you buy credits: a plan adds them every week or month, and the balance you already have is kept.

PlansWeekly $9.99, Monthly $29.99, Monthly 3.6× $99.99. Credits are added each time a plan renews and never expire.Dashboard → Plans Change or cancelA bigger plan starts now, prorated; a smaller one at the end of the period. Cancel in Manage subscription; the plan runs to the end of the period.Dashboard → Plans Credit packsFor subscribers who need more before the renewal: Small $12.99 → 779, Medium $24.99 → 1,499 credits, once.Dashboard → Plans

Also new: 1.2.1

Longer scene_prompt and Fix a scene description (2,000 characters), the real error_codeon failed jobs, and talking heads that keep the photo's outfit and place in every clip. Nothing to change in your requests. Changelog

Videos

Talking-head videosVoiced from a script or your recording, at 480P, 768P (default) or 1080P. A 15 s video is 30 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-10-11 Not enough creditsA 402 says what the call needs and what you have. Nothing is charged.402 INSUFFICIENT_CREDITS

Upgrade in four changes

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

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": 30
  }'

# 200 → { "workflow_id": "partner_h3t_…", "status": "queued", "credits_reserved": 30,
#         "price_table_version": "2026-10-11", "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
Video, 30 s (talking head or scenes, any resolution)	44
Video, 60 s (talking head or scenes, any resolution)	73
15 s talking head, 768P, your audio	30
15 s scene video, 768P, 2 scene photos	30
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