Generations

Generate images, video, and lipsync "talk" clips for a character, then poll for the finished media.

A generation produces an image, video, or lipsync “talk” clip for an existing character.

Create a generation

POST /v1/generations

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

Field	Type	Required	Default	Description
`character_id`	string (UUID)	yes	—	A character you own
`type`	enum	yes	—	`image`, `video`, or `talk`
`prompt`	string	yes	—	1–2000 characters
`model`	string	no	per-type default	See Pricing
`options`	object	no	—	Per-type options (below)
`webhook_url`	string	no	—	Held — returns `503 webhook_delivery_unavailable`

`options`

All optional. Which ones apply depends on type and mode.

Field	Default	Applies to	Description
`aspect_ratio`	`9:16` image, `16:9` video	image, video
`style`	`editorial`	image, video remix	Style modifier
`hd`	`false`	image	Higher resolution; charge may change by model/resolution
`duration`	`5` video, `10` talk	video, talk	1–15s ceiling; each model/mode may narrow it
`quality`	`pro`	video, talk	`standard` or `pro`
`generate_audio`	model-dependent	video	Generate an audio track where supported
`include_character`	model-dependent	image, video	Add the authorized character reference
`image_mode`	`generate`	image	`generate`, `remix`, `edit`
`video_mode`	`create`	video	`create`, `extend`, `remix`, `edit`, `lipsync`
`lipsync_model`	`kling-avatar`	video lipsync	`kling-avatar`, `heygen-avatar-4`, `ltx-lipsync`
`motion_intensity`	`medium`	video create	`low`, `medium`, `high`
`character_orientation`	`image`	video remix	`image`, `video`
`keep_original_sound`	`false`	video remix/edit	Preserve source audio where supported
`reference_video`	—	video remix/edit	Motion source video URL
`start_frame`	—	video, talk	Starting frame image URL
`input_image`	—	image edit	Image to transform URL
`audio_url`	—	talk, video lipsync	Audio for the character to speak
`expression`	`neutral`	talk	Character expression
`reference_images`	`[]`	image, video	Image: max 3; video maxima are model-specific (up to 10)

All URL fields are SSRF-validated (HTTPS only, trusted domains only).

{
  "data": {
    "id": "gen_uuid",
    "status": "processing",
    "type": "image",
    "credits_used": 3,
    "credits_remaining": 247,
    "created_at": "2026-03-29T..."
  }
}

List generations

GET /v1/generations

Paginated. Filters are strict — each must be non-empty and appear only once, or you get 400 invalid_filter (before any lookup). If both cursor and filter are invalid, invalid_cursor wins.

Query param	Description
`type`	`image`, `video`, `talk`, `character_create`
`character_id`	Filter by character UUID
`status`	`pending`, `processing`, `completed`, `failed`
`cursor`, `limit`	Pagination

Poll for the result

GET /v1/generations/:id

Poll until status is completed or failed.

While processing:

{
  "data": {
    "id": "gen_uuid",
    "type": "image",
    "status": "processing",
    "prompt": "walking through Tokyo at night",
    "character_id": "uuid",
    "credits_used": 3,
    "completed_at": null,
    "error_message": null
  }
}

When completed — the media is in output:

{
  "data": {
    "id": "gen_uuid",
    "status": "completed",
    "output": {
      "url": "https://cdn.someone.app/.../image_001.png",
      "thumbnail_url": "https://cdn.someone.app/..."
    }
  }
}

Delete a generation

DELETE /v1/generations/:id