---
title: "Create Avatar Looks"
method: POST
path: "/v3/avatars/looks"
tags: ["Avatars"]
---

# Create Avatar Looks

`POST /v3/avatars/looks`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/avatars/looks`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Generates new looks for an existing avatar from `reference_look_id`. `type: look_pack` applies a Look Pack; `type: template` applies one look template and produces two looks. Billing happens when the request is accepted: an API key is charged 1 API credit per look, and a connected integration (OAuth, including MCP) the method's standard price from workspace credits. Free-tier MCP access cannot use this endpoint. Poll GET /v3/avatars/looks/{id} until each look finishes.

## Headers

- `Idempotency-Key` string

## Request body

- union: Request body for POST /v3/avatars/looks.
  - CreateLookPackLooksRequest: Generate a Look Pack's looks into the avatar an existing look belongs to.
    - `type` 'look_pack', required: Generation method. 'look_pack' applies a Look Pack template.
    - `reference_look_id` string, required: An existing avatar look used as the identity reference. The new looks are added to its avatar.
    - `template_id` string, required: The Look Pack template to apply: a public template, or an enterprise custom pack assigned to your workspace.
    - `aspect_ratio` '16:9' | '9:16'
  - CreateTemplateLooksRequest: Restyle an existing avatar look into a single look template; the results are added to its avatar.
    - `type` 'template', required: Generation method. 'template' restyles the reference look into a single look template, producing two looks in the template's aspect ratio.
    - `reference_look_id` string, required: An existing avatar look used as the identity reference. The new looks are added to its avatar.
    - `template_id` string, required: The single look template to apply: a public template, or an enterprise custom template assigned to your workspace. A Look Pack is applied with type 'look_pack' instead.

## Response `200`

Successful response

- object
  - `data` CreateAvatarLooksResponse: Response for POST /v3/avatars/looks.
    - `group_id` string, required: The avatar group the looks were added to. Pass it as the group_id filter of GET /v3/avatars/looks to list them all.
    - `looks` CreatedLookRef[], required: The new looks, one per generated image, in output order.
      - `id` string, required: ID of a new look. Poll GET /v3/avatars/looks/{id}: its status stays 'processing' until it is either 'completed' (preview available, and the id is usable as avatar_id for POST /v3/videos) or 'failed' (see its error).

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `402`: Insufficient credit
- `403`: Forbidden — `error.code` is one of: `forbidden`, `resource_access_denied`.
- `404`: Resource not found
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/avatars/looks/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)