Describe a character and POST /v3/avatars with type: "prompt" generates it. The same call does double duty: pass an existing look as avatar_id and the prompt becomes a new outfit, setting, or style for that character instead of a new person.
prompt holds up to 1000 characters. aspect_ratio takes 16:9, 9:16, 1:1, 4:5, 5:4, or auto, which lets the model choose and matches a reference image’s ratio when one is given. Omitting it is the same as auto.The character is fully synthetic, so no real person is depicted and no consent step applies.The referenced look’s image conditions the generation, so the person stays recognisable while the prompt changes everything around them. The result saves to that character automatically.This works from any starting point: a digital twin, a photo avatar, or an earlier prompt avatar. Any of the resulting looks can be the reference for the next one. Up to three reference_images add wardrobe, style, or setting guidance, each given as a url, an asset_id from POST /v3/assets, or base64 content. Use them alone to steer a brand-new character, or layer them on an avatar_id reference.A crop showing only the garment keeps the reference about wardrobe and fabric, leaving the face to the avatar_id reference. Reference and destination
Two fields decide where the look comes from and where it lands:
Changed behavior (June 2026): avatar_group_id used to condition the generation on one of the group’s looks. It now only controls where the result is saved. Pass the base look’s id as avatar_id for character consistency. See the changelog. Writing the prompt
Name the age, expression, wardrobe, setting, and light. Camera direction is obeyed when it is explicit, as in “turned three-quarters toward camera left, with clean space on the left of the frame”. Texture words such as “natural matte skin, visible pores, no retouching” pull toward realism, and naming a lens or aperture pushes further.
Wait for it, then render
Poll GET /v3/avatars/looks/{look_id} until status leaves processing. A completed look returns preview_image_url and its supported_api_engines. Then pass the look id as avatar_id to POST /v3/videos with a voice_id from GET /v3/voices.
Prompt avatars render on Avatar V, IV, and III. Check supported_api_engines before requesting a specific engine.
A referenced avatar_id that does not exist returns 404 with error.code of avatar_not_found. One that has no usable image, or that is not in the avatar_group_id you gave, returns 400 with invalid_parameter.
