Promoat.Partner API

Building blocks

First-frame images

Generate a 9:16 still of your character — the exact shot a talking-head video opens on, or the realistic photo a scene video is built from. Cheap to iterate on before you spend video credits.

Generate a still

POST/api/partner/v1/images/first-frame

Instant. Costs 4 credits, charged immediately (refunded if it fails). The output is always 9:16.

FieldTypeDescription
character_iduuid requiredFrom POST /characters.
kind"talking_head" | "moving_scene"talking_head (default): the opening frame of a talking-head video. moving_scene: the realistic photo for a scene video.
scene_descriptionstring ≤2000The brief — where the character is and what the shot shows. One of scene_description / scene_prompt / script is required.
scene_promptstring ≤400Short visual direction for the shot.
scene_photosarray ≤3Photos of your real place, product or prop: { url, role?, caption? }.
scriptstring ≤4000What the video will say — context only.
languagestringSpoken language, for context.
Request
curl -X POST https://platform.promoat.ai/api/partner/v1/images/first-frame \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "CHARACTER_ID",
    "kind": "talking_head",
    "scene_description": "standing at the counter of a sunlit bakery, smiling at the camera"
  }'
Response
{
  "image_url": "https://…/first-frame.png",
  "asset_id": "4c1e…",
  "frame_id": "4c1e…",
  "kind": "talking_head",
  "credits_charged": 4
}

frame_id equals asset_id. On failure the body is { "error": "First-frame generation failed", "error_code", "message" } with error_code such as FIRST_FRAME_NOT_VERTICAL or CHARACTER_IMAGE_UNAVAILABLE.

The cheap-iteration workflow

  1. Generate frames until the scene, outfit and framing look right (4 credits per try).
  2. Queue the video with first_frame_asset_id set to the winner's frame_id (or first_frame_url to its URL). The job animates exactly that still.
Match the kind to the video

A talking_head frame works only on a talking-head video, and a moving_scene frame only on a scenes video. A mismatch → 400 FIRST_FRAME_KIND_MISMATCH (field first_frame_asset_id). Frames made before 1.1.0 count as talking-head frames.

It also saves money on the video

A video that gets your frame drops its first_frame line — a 15 s talking head at 768P goes from 125 to 121 credits.

Try it

Try itGET/api/partner/v1/charactersfree
Add your API key in the sidebar to enable this.
Try itPOST/api/partner/v1/images/first-framecharges 4 credits
Add your API key in the sidebar to enable this.
← PreviousText-to-speechNext →Talking-head videos