create avatar video

Creates an asynchronous avatar-video render backed by a normal recorded Anam session. A saved persona contributes only its snapshotted avatar, voice, language, model and director notes; its greeting, brain, prompt and tools never run. The request is rejected rather than queued when either concurrency limit is full.

POST /v1/avatar-videos

cURL

savedPersona

curl --request POST \
  --url https://api.anam.ai/v1/avatar-videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "script": "Welcome to the product tour.",
  "personaId": "00000000-0000-0000-0000-000000000000",
  "metadata": {
    "customerJobId": "onboarding-42"
  }
}
'

202

{
  "id": "avv_123",
  "status": "pending",
  "truncated": true,
  "effectiveMaxDurationSeconds": 123,
  "region": "eu",
  "zeroDataRetention": true,
  "content": {
    "available": true,
    "deleteAt": "2023-11-07T05:31:56Z",
    "url": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "completionReason": "script_completed",
  "durationSeconds": 123,
  "sessionId": "<string>",
  "failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true
  },
  "retryOf": "<string>",
  "startedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Stable caller-generated key. Reusing it with the same body returns the original resource; a different body returns 409.

Required string length: 1 - 255

Body

application/json

Option 1

Option 2

script · string · required

Exact text spoken through TTS; the brain is never invoked.

Required string length: 1 - 20000

personaId · string · required

Saved persona to snapshot. Mutually exclusive with direct configuration fields.

avatarId · string

voiceId · string

avatarModel · string

Example:

"cara-4-latest"

directorNotes · object | null

Show child attributes

languageCode · string

Example:

"en"

voiceSpeed · number

Required range: -1 <= x <= 1

voiceGenerationOptions · Cartesia Sonic-3 · object

Voice generation options for Cartesia Sonic-3 models.

Cartesia Sonic-3

ElevenLabs V1

ElevenLabs V2

ElevenLabs V3

ElevenLabs V4

Fish Audio

Show child attributes

videoWidth · integer

Required range: x >= 1

videoHeight · integer

Required range: x >= 1

environment · object

Optional engine routing for the render session, as on the session token endpoint. Internal accounts only; other accounts get 403.

Show child attributes

metadata · object

Caller metadata, up to 16 KB serialized. It is stored and returned as sent. A zero-data-retention video, which includes every video created on a regional host, doesn't store it: its responses return {}. Keep your own mapping from the video id to your records.

retentionSeconds · integer

Seconds to keep the recording, session report and job content after the job ends; Lab then deletes them within about a minute. Without a value, they are kept until deleted. Download the recording as soon as it is ready.

Required range: 300 <= x <= 2592000

Response

202

application/json

Accepted. Poll the returned resource.

id · string · required

Example:

"avv_123"

status · enum<string> · required

Available options: pending, running, finalizing, completed, failed, cancelled

truncated · boolean · required

effectiveMaxDurationSeconds · integer · required

region · enum<string> | null · required

Region the job is pinned to: eu when created on api.eu.anam.ai, us when created on api.us.anam.ai. Its session, recording and retries stay in that region. Null when created on api.anam.ai.

Available options: eu, us, null

zeroDataRetention · boolean · required

Whether the job runs with Zero Data Retention, which keeps its script, and a direct request's style prompts, out of Lab's database. A persona-sourced job's director notes stay in its stored persona. Always true for a job created on a regional host.

content · object · required

Show child attributes

createdAt · string<date-time> · required

metadata · object · required

completionReason · enum<string> | null

Available options: script_completed, max_duration_reached, cancelled, null

durationSeconds · number | null

sessionId · string | null

Underlying normal EngineSession ID. Use its recording deletion endpoint for deletion.

failure · object | null

Show child attributes

retryOf · string | null

startedAt · string<date-time> | null

completedAt · string<date-time> | null