> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt to Avatar

> Generate a synthetic avatar from a text description with POST /v3/avatars, or put an avatar you already have into a new outfit and setting by passing it as the visual reference.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

Describe a character and [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar) 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.

> [tab] A new character
>
> ```bash theme={null}
> 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.

> [tab] A new look for your avatar
>
> ```bash theme={null}
> 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](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-video.md), a [photo avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-photo.md), or an earlier prompt avatar. Any of the resulting looks can be the reference for the next one.

> [tab] With reference images
>
> ```bash theme={null}
> 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`](https://heygen-1fa696a7.mintlify.site/docs/upload-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 |

> [!WARNING]
>
> **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](https://heygen-1fa696a7.mintlify.site/changelog.md).

## Writing the prompt

> [!TIP]
>
> 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](https://heygen-1fa696a7.mintlify.site/writing-effective-video-prompts) goes deeper.

## Wait for it, then render

Poll [`GET /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look) 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`](https://heygen-1fa696a7.mintlify.site/reference/create-video) with a `voice_id` from [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices).

Prompt avatars render on [Avatar V, IV, and III](https://heygen-1fa696a7.mintlify.site/models). 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.