Skip to main content

Prerequisites

A portrait photo (PNG or JPEG) — clear, front-facing, good lighting
A voice_id for the voice you want. Use GET /v3/models/audio/voices to browse voices.

Step 1 — Create a Photo Avatar

Upload your photo and create a Photo Avatar with POST /v3/avatars:
To use a local file, upload it first with POST /v3/assets and pass "file": {"type": "asset_id", "asset_id": "RETURNED_ASSET_ID"} instead. The response includes an avatar_item with an id — this is your avatar_id for video creation.

Step 2 — Generate the video

Use POST /v3/videos with type: "avatar" and the Photo Avatar ID:

Step 3 — Poll for completion

Generation is asynchronous. Poll GET /v3/videos/{video_id} until status is completed, then download video_url.

Motion and expressiveness

Photo avatars (avatar_type: photo_avatar) take a motion_prompt that directs body motion and hand gestures (e.g. “nodding gently”). On Avatar IV they also take expressiveness: high, medium, or low (default low). On Avatar 6, set engine.motion_expressiveness instead.
Every other field, such as background, remove_background, voice_settings, and callback_url, is in the Create Video reference.
Photo quality matters. Use a well-lit, front-facing portrait with a neutral expression for the best results. Avoid sunglasses, hats covering the forehead, or extreme angles.

Using a preset Photo Avatar

You can skip avatar creation and use a public preset avatar instead:
Pick any id from the response and use it directly as your avatar_id in POST /v3/videos.