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"
}
}
'
{
"id": "avv_123",
"status": "pending",
"truncated": true,
"effectiveMaxDurationSeconds": 123,
"content": {
"available": true,
"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"
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}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 --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"
}
}
'
{
"id": "avv_123",
"status": "pending",
"truncated": true,
"effectiveMaxDurationSeconds": 123,
"content": {
"available": true,
"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"
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}{
"code": "<string>",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": {}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Stable caller-generated key. Reusing it with the same body returns the original resource; a different body returns 409.
Required string length:
1 - 255Body
application/json
- Option 1
- Option 2
Exact text spoken through TTS; the brain is never invoked.
Required string length:
1 - 20000Saved persona to snapshot. Mutually exclusive with direct configuration fields.
Example:
"cara-4-latest"
Show child attributes
Show child attributes
Example:
"en"
Required range:
-1 <= x <= 1Voice generation options for Cartesia Sonic-3 models.
- Cartesia Sonic-3
- ElevenLabs V1
- ElevenLabs V2
- Fish Audio
Show child attributes
Show child attributes
Required range:
x >= 1Required range:
x >= 1Caller metadata, up to 16 KB serialized.
Response
Accepted. Poll the returned resource.
Example:
"avv_123"
Available options:
pending, running, finalizing, completed, failed, cancelled Show child attributes
Show child attributes
Available options:
script_completed, max_duration_reached, cancelled, null Underlying normal EngineSession ID. Use its recording deletion endpoint for deletion.
Show child attributes
Show child attributes
Last modified on September 4, 2026
Was this page helpful?