Promoat.Partner API

Reference

Changelog

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

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 in 1.1.

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

EndpointWhat it does
POST /videos/scene-planSplit a script into clip lines (free).
GET /videos/{id}/scenesList a video's scenes.
POST /videos/{id}/fix-sceneRedo one scene.
POST /videos/{id}/edit-scriptRewrite lines.
POST /videos/{id}/fix-soundReplace the sound.
GET /voices/presetsList studio voices (free).
POST /voices/{id}/recloneRe-clone a voice.
POST /characters/{id}/regenerateNew sheet, same person.

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 default credit purchase is now the $19.99 pack — 1,499 credits on the current tier.

Rollback

Switching back to the previous engines

The operator of this deployment can switch video jobs back to the previous engines by setting PARTNER_LEGACY_MODELS_ENABLED=true. Under it, the new-only fields are ignored with a FIELD_IGNORED warning and the previous pricing applies.

← PreviousMCP server