Generate avatar videos

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.

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

Create a video

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

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:

{
  "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:

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.

Avatar video API reference

See every request field, response, operation, and error.

Introduction

Personas

Avatar videos

Security & Compliance

Resources

Generate avatar videos

Create a video

Use a saved persona

Check the status and download

Avatar video API reference

​Create a video

​Use a saved persona

​Check the status and download

Avatar video API reference

Create a video

Use a saved persona

Check the status and download