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, except with Zero Data Retention, where the default is 600 and the most 43200. 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