> ## 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.

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=d16cda8ab7835eed66c6a205d16e631f" alt="" noZoom width="1400" height="788" data-path="images/theme/research-8.webp" />

Describe a character and [`POST /v3/avatars`](/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.

<Tabs>
  <Tab title="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>

  <Tab title="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](/docs/avatar-from-video), a [photo avatar](/docs/avatar-from-photo), or an earlier prompt avatar. Any of the resulting looks can be the reference for the next one.
  </Tab>

  <Tab title="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`](/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.
  </Tab>
</Tabs>

## 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](/changelog).
</Warning>

## 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.
</Tip>

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](/writing-effective-video-prompts) goes deeper.

## Wait for it, then render

Poll [`GET /v3/avatars/looks/{look_id}`](/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`](/reference/create-video) with a `voice_id` from [`GET /v3/voices`](/docs/voices/search-voices).

Prompt avatars render on [Avatar V, IV, and III](/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`.