Reference

Changelog

What changed for integrators, version by version. Existing requests keep working; read the "behaviour changes" list before you upgrade.

1.3.0

Requests and responses are unchanged; credits now come from a plan.

• Plans. The dashboard sells the Promoat app's plans, at the app's prices: Weekly $9.99 for 559 credits a week, Monthly $29.99 for 2,219 credits a month, Monthly 3.6× $99.99 for 7,999 credits a month. Credits are added each time a plan renews and never expire. See Buying credits.
• Plan changes. A bigger plan or a longer interval starts now, prorated; a smaller plan or a shorter interval at the end of the period. Cancelling keeps the plan to the end of the period. See Changing or cancelling a plan.
• Credit packs for subscribers, bought once: Small $12.99 for 779, Medium $24.99 for 1,499 credits.
• Balances are kept, and job prices are unchanged (price table 2026-10-11).
• Onboarding shows moving examples of real output. It still ends on the 25 trial credits; plans are on the dashboard.
• Embedded partners: the signed /partner/billing link and POST /billing/checkout-session work as before.

1.2.1

Requests, responses and prices are unchanged.

• scene_prompt takes up to 2,000 characters (was 400) and the Fix a scene description up to 2,000 (was 500). The whole text is used; longer is still 400 INVALID_BODY.
• Failed jobs report their real error_code. Some failures that ran out of retries showed INTERNAL; they now carry their own code, such as LINE_TOO_LONG, VOICE_UNAVAILABLE, FIX_NOT_APPLIED or a PROVIDER_* code (see Why a job failed). A line that cannot fit its scene fails at once.
• Talking heads keep the photo's outfit, hair, place and framing in every clip (first render and every edit), and the engine no longer draws captions on them. use_dynamic_captions works as before.

1.2.0

Requests and responses are unchanged; prices are lower.

• New video engine and prices (price table 2026-10-11). A video is priced by its length, the same at every resolution, for talking heads and scenes: with your own audio 15 s is 30 credits and 60 s is 73. See Credits & pricing.
• Edits are priced the same way: an 8 s scene is 9 (21 with a new frame); Fix sound with a new 15 s take on a talking head is 18.
• Quote lines no longer include reference_allowance.

1.1.1

Additive: existing fields and values are unchanged.

• Every error on every endpoint has error, error_code (UPPER_SNAKE) and message. Old error strings and the lowercase code are kept; every 401 now has error_code UNAUTHORIZED.
• Clone and TTS errors: error_code is now NO_SPEECH, CLONE_UNAVAILABLE and VOICE_UNAVAILABLE (1.1.0 sent no_speech, clone_unavailable, voice_not_found; those values moved to code).
• topic / audience on /videos return a FIELD_IGNORED warning: they never changed the video. Put the brief in video_idea / scene_prompt.

1.1.0

A guided tour with a link to every new feature is on What's new.

Behaviour changes

• New video engines. Talking-head and scene videos now run on the current engines: sharper output, and prices follow price table 2026-09-30 (returned as price_table_version). Example: a 15 s talking head at 768P with your own audio is 125 credits. See Credits & pricing.
• Default resolution is now 768P (was 480p). 480P, 768P and 1080P are accepted; 720p is served as 768P with a RESOLUTION_MAPPED warning.
• /tts uses the v4 voice model. Same request, but voices sound different from before.
• Captions remain a talking-head add-on (10 credits); captions_position now also accepts center.
• The quote is a ceiling. Video jobs reserve the quote before starting and charge min(actual, reserved). Jobs quiet for 75 minutes fail with STALE_TIMEOUT and are refunded.
• First voice clone is free, once per account; later clones 30 credits.
• Non-https URLs. A non-https first_frame_url or audio_url is ignored with a FIELD_IGNORED warning instead of being used.
• Selfie URL check. Selfies and reference images that fail the URL check are dropped with a FIELD_IGNORED warning; we store re-hosted copies, never your URL.
• Legacy tuning fields (fast, lipsync, narration_mode, …) are accepted and ignored with a warning. audio_url is now allowed on scene videos.

Errors

• Errors on /videos, /videos/estimate and the first-frame 500 gained an error_code; since 1.1.1 every error on every endpoint has error, error_code and message. Old error strings and HTTP statuses are kept; new failures use the UPPER_SNAKE code as error. See Errors & limits.
• FIRST_FRAME_KIND_MISMATCH: a first_frame_asset_id must be made for the same video type.
• 503 TRY_AGAIN when briefly unavailable (nothing charged).

New endpoints

New fields

• /videos: scene_photos, scene_prompt, scene_lines, video_mode, voice_mode + target_seconds (silent videos), voice_settings, language, first_frame_asset_id, expected_credits, client_request_id. The response adds credits_quoted, job_type, resolution, price_table_version, warnings, duplicate; the estimate adds lines and clips.
• Idempotency: Idempotency-Key header or client_request_id — retries return the original job with duplicate: true.
• expected_credits: lock the price; a higher quote → 409 QUOTE_MISMATCH. A paid fix-sound requires it — call with dry_run: true first.
• Job status: phase, progress, poster_url, error_code, source_workflow_id, and editable / scenes_url on the result. New workflow-id prefixes partner_h3t_, partner_h3v_, partner_se_, partner_fs_.
• /images/first-frame: kind, scene_prompt, scene_photos, script, language; response adds frame_id.
• /characters: response adds presenter_gender, head_covering, warnings.
• /tts: language; response adds characters; a dead voice → 409 VOICE_UNAVAILABLE.

Added after review (same release)

• Scene photos: a photo that can't be fetched safely while a scene job runs is dropped with a SCENE_PHOTO_DROPPED warning, and the job is re-priced with the photos actually used (never above the reserve). See Scene photos and roles.
• Free first clone: after 20 failed free attempts the API answers 409 FREE_CLONE_ATTEMPTS_EXHAUSTED instead of charging. Concurrent clones past the voice cap get 409 VOICE_LIMIT_REACHED and are refunded.
• One Idempotency-Key is race-safe across talking-head and scene requests: one job is made.

Billing

• The dashboard sold credits as a one-time pack. Since 1.3.0, credits come from a plan.

Rollback