Building blocks
First-frame images
Generate a still of your character in a scene — the exact shot a talking-head video would open on. Six credits to see the framing before you spend video money on it.
Generate a still
POST/api/partner/v1/images/first-frame
Costs 6 credits, charged immediately.
| Field | Type | Description |
|---|---|---|
| character_id | uuid required | From POST /characters. |
| scene_description | string ≤2000 required | The "video idea" — where the character is and what the shot shows ("standing at the counter of a sunlit bakery, holding a croissant"). |
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",
"scene_description": "standing at the counter of a sunlit bakery, smiling at the camera"
}'Response
{
"image_url": "https://…/first-frame.png",
"asset_id": "…",
"credits_charged": 6
}The cheap-iteration workflow
This endpoint exists so you can iterate on the look for pennies instead of dollars:
- Generate first frames until the scene, outfit, and framing look right (6 credits per try).
- Queue the video with
first_frame_urlset to the winner — the job skips its own scene planning and image generation and animates exactly that still.
It also saves money on the video
A talking-head job that receives first_frame_url doesn't bill its own first-frame line item — you effectively pre-paid the 6 credits here. Details in Talking-head videos.
Try it
Grab a character_id first:
Try itGET/api/partner/v1/charactersfree
Add your API key in the sidebar to enable this.
Try itPOST/api/partner/v1/images/first-framecharges 6 credits
Add your API key in the sidebar to enable this.