> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate avatar videos

> Render a supplied script as an asynchronous avatar video using a saved persona or an avatar and voice.

Avatar videos turn a script into a recorded MP4 without opening an interactive conversation. Create a video from your backend, check its status, then download it when it is ready.

<Note>Call the avatar-video API from your backend. Keep your Anam API key out of browsers and mobile apps.</Note>

## Create a video

Provide an `avatarId` and `voiceId` to create an ephemeral persona for the video:

```bash theme={"system"}
curl --request POST https://api.anam.ai/v1/avatar-videos \
  --header "Authorization: Bearer $ANAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: onboarding-welcome-v1" \
  --data '{
    "script": "Welcome to the product tour.",
    "avatarId": "YOUR_AVATAR_ID",
    "voiceId": "YOUR_VOICE_ID",
    "directorNotes": {
      "presetStyle": "warm"
    }
  }'
```

The API returns `202 Accepted` with an avatar-video resource.

Every create request requires an `Idempotency-Key`. If you need to repeat the same request after a network error, reuse the same key to receive the original video job instead of creating another one. Use a new key for a different video.

## Use a saved persona

Alternatively, replace the direct avatar and voice fields with a saved `personaId`:

```json theme={"system"}
{
  "script": "Welcome to the product tour.",
  "personaId": "YOUR_PERSONA_ID"
}
```

The saved persona contributes its avatar, voice, language, avatar model, and director notes. Only the submitted script is spoken; its greeting, brain, prompt, and tools do not run. Do not combine `personaId` with direct configuration fields.

## Check the status and download

Use the returned `id` to fetch the latest status:

```bash theme={"system"}
curl https://api.anam.ai/v1/avatar-videos/AVATAR_VIDEO_ID \
  --header "Authorization: Bearer $ANAM_API_KEY"
```

The status moves from `pending` to `running`, `finalizing`, and `completed`. Download the MP4 from `content.url` when `content.available` is `true`. The URL expires after one hour; fetch the resource again to get a fresh URL.

See the API reference for all voice, model, director-note, language, video-size, list, cancel, retry, and error options.

<Card title="Avatar video API reference" icon="code" href="/docs/api-reference/avatar-videos/create-an-avatar-video">
  See every request field, response, operation, and error.
</Card>