Skip to main content
Every avatar you create is a look on a character. The look id is what you pass as avatar_id when you create a video. The character, called an avatar group, is the identity that holds all of that person’s looks together. Browse them with Avatar Groups and Avatar Looks.

​
Pick a starting point

The first three go through POST /v3/avatars, distinguished by the type field. The fourth generates looks for an existing character: one at a time in your own words through the same endpoint, or a curated set in one call through POST /v3/avatars/looks.

​
What creation returns

POST /v3/avatars answers the same shape for all three types: the new look in avatar_item, the character it belongs to in avatar_group.
Creation is asynchronous, so a new look starts at status: "processing". Poll GET /v3/avatars/looks/{look_id} until it reports completed. Before requesting a specific engine, check the look’s supported_api_engines against Models. The character carries a status of its own, covering consent and moderation rather than training, so avatar_group.status and avatar_item.status move independently. avatar_group.status follows consent_status: pending_consent while consent is outstanding, failed if it was rejected, and completed otherwise. A photo or prompt avatar renders as soon as its look reports completed. A digital twin renders once the look is completed and its group has cleared consent, so wait for both. A digital twin generates video once the person depicted has agreed to be cloned, which is what consent_status tracks. Photos and prompts depict no trained likeness, so a group created from one reports consent_status of null. The field belongs to the group, so a photo or prompt look added to an existing twin’s group carries that group’s status. Avatar Consent covers the POST /v3/avatars/{group_id}/consent flow and the three levels of access to it.

​
One character, many looks

Adding looks to a character you already have keeps one identity across every video: pass avatar_group_id when you create, hand an existing look to a prompt, or apply a Look Pack. List everything a character owns with GET /v3/avatars/looks?group_id=..., rename a look with PATCH /v3/avatars/looks/{look_id}, and remove one with DELETE. Deleting the last look in a character deletes the character with it.