A digital twin is trained from footage of a real person, and clones a voice from the same recording so the twin speaks in the subject’s own voice.
1
Create the twin
file also takes { "type": "asset_id", "asset_id": "..." } from POST /v3/assets, or base64 content.avatar_group_id decides which character the twin belongs to:- Pass an existing
avatar_group_idto add the twin as another look of a character you already have. Only do this for the same person, since consent is tracked per group. - Leave it out to create a new avatar group (a new character) for this person. The new group id is returned as
avatar_group.id.
A
url input is fetched when you call the endpoint and is capped at 32 MB, the same as POST /v3/assets. Signed or presigned HTTPS URLs work as long as they are reachable at that moment, but they do not raise the cap. Base64 input is capped at 16 MB after decoding. For recommended footage (about 2 minutes at 1080p), use direct upload, then pass { "type": "asset_id", "asset_id": "asset_abc123" }. An asset_id stays usable until you delete it, so reuse the same one if you retry creation.avatar_item.id is the avatar_id you render with, and avatar_group.id is what the consent flow acts on. Store the group id per person, since it is also the avatar_group_id you pass to add more looks of them later.2
Wait for training
Poll To be notified instead of polling, subscribe a webhook endpoint to the
GET /v3/avatars/looks/{look_id} until status leaves processing; training usually completes within a few minutes.instant_avatar.success and instant_avatar.fail events.A failed look carries an error object: training_failed when the footage could not be trained, moderation_failed when it did not pass content review. The reason is in error.message.3
Collect consent
POST /v3/avatars/{group_id}/consent returns a link, valid for 24 hours, that the subject opens to record a short statement on camera. Enterprise workspaces can upload a pre-recorded consent video or have the step waived.An uploaded consent video must be under 35 seconds and show the same person as the footage. Record it as its own short clip, separate from the training footage. See Avatar Consent for what it must contain.Avatar Consent has the three levels of access and the full flow.4
Render
Render once the look reports The Digital Twin recipe walks the render end to end, and Models compares the engines a twin supports.
status: "completed" and the group has cleared consent. No other publish step is needed.Pass the look id as avatar_id. Omitting voice_id falls back to the character’s default voice, which is the group’s linked voice when the twin joined an existing group. Pass avatar_item.default_voice_id from the create response to speak in the voice cloned from this footage.Footage that trains well
Longer footage with varied natural speech gives the model more to learn from. About 2 minutes at 1080p gives the best twin quality.
A clip like that is usually larger than 32 MB, so upload it with direct upload, which accepts video files up to 200 MB, and pass the
asset_id. If your recording is over 200 MB, export it at a lower bitrate before uploading.
The cloned voice
Creating a digital twin clones one voice from the training footage automatically. There is no separate voice request and no opt-in step. The id is returned immediately as
avatar_item.default_voice_id, while the avatar and the voice finish processing.The cloned voice is its own resource. Deleting the twin’s look or group does not delete it; remove it with DELETE /v3/voices/{voice_id}.avatar_item.default_voice_id is the voice cloned from this request’s footage. avatar_group.default_voice_id is the effective voice for the character: a linked group voice takes precedence, falling back to the new look’s clone.
Set the character’s voice deliberately by sending default_voice_id to PATCH /v3/avatars/{group_id}. Any voice in your workspace works, including cloned voices.
To give the same person more outfits and settings, generate looks from a prompt or a Look Pack.