Characters

Create a consistent AI character with a headshot and full-body image, then list, regenerate, or revert it.

A character is the reusable identity you generate images, video, and audio for. Creating one triggers AI generation of a headshot and a full-body image.

Create a character

POST /v1/characters

Asynchronous — returns 201 with status: "generating". Requires an Idempotency-Key.

Field	Type	Required	Default	Description
`name`	string	yes	—	1–100 characters
`parameters`	object	yes	—	Character traits (below)
`reference_image_urls`	string[]	no	—	Up to 4 immutable CDN URLs from media upload
`webhook_url`	string	no	—	Held — supplying it returns `503 webhook_delivery_unavailable`

`parameters`

Field	Default	Description
`creationType`	`human`	`human`, `fantasy`, `prompt`, or `image`
`gender`	—	e.g. `female`, `male`, `non-binary`
`age`	—	e.g. `20s`, `25-34`
`ethnicity`	—	e.g. `mixed`, `east-asian`
`skinTone`	—
`eyeColor`	—
`artStyle`	`hyper-realistic`	e.g. `photorealistic`, `anime`
`customDetails`	—	Free-text description details
`prompt`	—	Full custom prompt
`fantasyMode`	—	Fantasy creation mode
`creatureType`	—	Fantasy creature type
`colorScheme`	—	Fantasy color scheme
`creatureSize`	—	Fantasy creature size
`mood`	—	Character mood / expression

{
  "data": {
    "id": "uuid",
    "name": "My Character",
    "status": "generating",
    "generation_id": "uuid",
    "credits_used": 10,
    "credits_remaining": 240,
    "created_at": "2026-03-29T..."
  }
}

The credits_used in the accepted response is the authoritative charge.

List characters

GET /v1/characters

Paginated (cursor). Query params: cursor, limit.

Get a character

GET /v1/characters/:id

Returns the full character, including headshot_url, fullbody_url, parameters, and status. Poll this until status is ready or failed.

Regenerate a character

POST /v1/characters/{id}/regenerate

Starts a new headshot/full-body lifecycle for a ready, owned character. Requires an Idempotency-Key. The JSON body accepts an optional bounded custom_details edit instruction — use an empty string for a full regeneration.

201 + a generation Location — accepted; poll it.
200 — an exact terminal recovery.
202 — ambiguous outcome; retry the exact request with the same key.

Revert a regeneration

POST /v1/characters/{id}/revert

Atomically restores the immediately previous regeneration-owned version and confirms any required refund exactly once. Send an empty JSON object {} and an Idempotency-Key.

200 — reverted.
202 — still reconciling; retry the exact request.
409 — invalid resource state or idempotency reuse.

Revert completes against the character itself and does not create a separate polling resource.

Delete a character

DELETE /v1/characters/:id