Building blocks
Characters
A character is your AI presenter: one consistent face that appears in every image and video you generate. Create it once from selfies or a description, then reference it by id everywhere.
Two ways to create one
Photo mode reproduces the exact person in the selfies you provide — use it when your customer wants themselves (or their spokesperson) on camera. Description mode invents a presenter from free text — use it when any good-looking, on-brand face will do. You pick the mode implicitly by which fields you send.
Only upload selfies of people who have agreed to appear in generated video. You're responsible for having that consent for any likeness you clone.
Create a character
Costs 10 credits, charged immediately. Behind the scenes this renders a character sheet — the reference image the video pipeline uses to keep the face consistent shot to shot.
| Field | Type | Description |
|---|---|---|
| name | string ≤120 required | Your label for this presenter. |
| selfie_image_urls | string[] 1–3 | Photo mode. Public https URLs of clear selfies of the same person. Sending this makes it a photo-mode character. |
| edit_instructions | string ≤500 | Photo mode only — a tweak that keeps identity ("shorter hair", "wearing a chef jacket"). |
| description | string ≤2000 | Description mode. Free text describing the presenter to invent ("a warm, confident dentist in her 40s"). |
| reference_image_urls | string[] ≤3 | Description mode only — loose style inspiration (lighting, vibe). Never copied as an identity. |
| recast_attempt | integer ≥1 | Description mode only — bump this to force a noticeably different invented person from the same description. |
curl -X POST https://platform.promoat.ai/api/partner/v1/characters \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ava",
"description": "a friendly, upbeat presenter in her early 30s, casual smart outfit",
"reference_image_urls": [
"https://your-cdn.com/style/mood-lighting.jpg",
"https://your-cdn.com/style/wardrobe-ref.jpg"
],
"recast_attempt": 0
}'curl -X POST https://platform.promoat.ai/api/partner/v1/characters \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Chef Omar",
"selfie_image_urls": [
"https://your-cdn.com/selfies/omar-1.jpg",
"https://your-cdn.com/selfies/omar-2.jpg",
"https://your-cdn.com/selfies/omar-3.jpg"
],
"edit_instructions": "wearing a white chef jacket, slightly younger"
}'{
"character_id": "0b2f1c3e-…",
"name": "Ava",
"mode": "description",
"sheet_image_url": "https://…/character-sheet.png",
"character_sheet_text": "…",
"asset_id": "…",
"credits_charged": 10
}Open sheet_image_url to eyeball the presenter before spending video credits on them. Not happy with an invented face? Re-create with recast_attempt: 1 (then 2, 3…) for a different person.
List, get, delete
Returns your characters, newest first (up to 100): character_id, name, mode, sheet_image_url, created_at.
One character, including character_sheet_text.
Removes the character. Videos and assets already generated with it are untouched — see Assets.