Promoat.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
Free, as in the app — only a regenerate costs credits. Behind the scenes this renders a character sheet — the reference image video jobs use 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. A URL that fails our URL check (not https, private or unreachable host) is dropped with a FIELD_IGNORED warning; if every selfie fails you get 422. We store re-hosted copies, never your URL. |
| 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. Same URL check as selfies. |
| 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": 1
}'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": "…",
"presenter_gender": "female",
"head_covering": "none",
"asset_id": "…",
"credits_charged": 0,
"warnings": []
}presenter_gender is female | male | unknown; head_covering is none | hijab | niqab | headscarf | turban | kippah | unknown. Video jobs use both to keep the presenter consistent. Open sheet_image_url to check the presenter before spending video credits. Not happy with an invented face? Re-create with recast_attempt: 1 (then 2, 3…).
Regenerate the sheet
Body { "edit_instructions"?: "≤500 chars" }. Same person, new sheet: the character is updated in place (same character_id) and a new character_sheet asset is saved. 4 credits.
curl -X POST https://platform.promoat.ai/api/partner/v1/characters/0b2f1c3e-…/regenerate \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{ "edit_instructions": "same person, navy blazer instead of the jacket" }'
# → { "character_id": "0b2f1c3e-…", "sheet_image_url": "https://…", "asset_id": "…", "credits_charged": 4 }Errors: 404, 422 (the stored references can't be read), 402.
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.