Prompt to Avatar

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.

A new character
A new look for your avatar
With reference images

curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "prompt",
    "name": "Space Commander",
    "prompt": "Woman in her early 30s, confident expression, short silver hair, dark blue flight suit with mission patches, spacecraft bridge with holographic displays, cinematic lighting",
    "aspect_ratio": "16:9"
  }'

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.

curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "prompt",
    "name": "Sarah, navy blazer",
    "prompt": "Wearing a navy blazer, modern office with plants behind her, warm natural light",
    "avatar_id": "look_abc123"
  }'

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.

curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "prompt",
    "name": "Sarah, studio portrait",
    "prompt": "Wearing the coat from the reference, plain studio backdrop, soft key light",
    "avatar_id": "look_abc123",
    "reference_images": [
      { "type": "url", "url": "https://example.com/coat-reference.png" }
    ]
  }'

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:

`avatar_id`	`avatar_group_id`	Visual reference	Saved to
absent	absent	the prompt alone	a new character
absent	set	the prompt alone	that character
set	absent	the referenced look’s image	the referenced look’s character
set	set	the referenced look’s image	`avatar_group_id`, which the look must belong to

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.

Details you leave out get invented plausibly, including text on badges and props, so read the generated image before writing a script around it. Writing Effective Video Prompts goes deeper.

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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Reference and destination

Writing the prompt

Wait for it, then render

​Reference and destination

​Writing the prompt

​Wait for it, then render

Reference and destination

Writing the prompt

Wait for it, then render