> ## 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. # Create Avatar Looks > Generates new looks for an existing avatar. `reference_look_id` is an existing look used as the identity reference; the new looks are added to its avatar. `type` selects the method. `look_pack` applies a Look Pack: `template_id` is a public Look Pack template, or an enterprise custom pack assigned to your workspace, and the pack decides how many looks are generated; generation is always 16:9, and `aspect_ratio: "9:16"` center-crops the delivered frames to portrait. `template` restyles the look into a single look template, producing two looks in the template's aspect ratio. Billing happens when the request is accepted: an API key is charged 1 API credit per look generated; a connected integration is charged the method's standard price from the workspace's credits. Free-tier MCP access cannot use this endpoint. The response lists the new looks' ids; poll `GET /v3/avatars/looks/{id}` until each is `completed` or `failed`. ## OpenAPI ````yaml /openapi/external-api.json post /v3/avatars/looks openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Filler Word Removal description: '' paths: /v3/avatars/looks: post: tags: - Avatars summary: Create Avatar Looks description: >- Generates new looks for an existing avatar. `reference_look_id` is an existing look used as the identity reference; the new looks are added to its avatar. `type` selects the method. `look_pack` applies a Look Pack: `template_id` is a public Look Pack template, or an enterprise custom pack assigned to your workspace, and the pack decides how many looks are generated; generation is always 16:9, and `aspect_ratio: "9:16"` center-crops the delivered frames to portrait. `template` restyles the look into a single look template, producing two looks in the template's aspect ratio. Billing happens when the request is accepted: an API key is charged 1 API credit per look generated; a connected integration is charged the method's standard price from the workspace's credits. Free-tier MCP access cannot use this endpoint. The response lists the new looks' ids; poll `GET /v3/avatars/looks/{id}` until each is `completed` or `failed`. operationId: createAvatarLooks parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAvatarLooksRequestBody' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateAvatarLooksResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: >- template_id must refer to a Look Pack template; a single look template is applied with type 'template' param: template_id doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '402': description: Insufficient credit content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: insufficient_credit message: >- Insufficient credit to generate the looks. Add credits or choose a pack that generates fewer looks. param: null doc_url: null '403': description: >- Forbidden — `error.code` is one of: `forbidden`, `resource_access_denied`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: temporarily_unavailable: summary: Avatar look generation is temporarily unavailable value: error: code: forbidden message: >- Avatar look generation is temporarily unavailable. Please try again later. param: null doc_url: null paid_plan_required: summary: >- The connected integration cannot generate looks on the free tier value: error: code: forbidden message: >- Avatar look generation requires a paid plan. Upgrade to access this feature. param: null doc_url: null workspace_access_denied: summary: The workspace or avatar group does not allow look generation value: error: code: resource_access_denied message: Space is not allowed to create a private avatar param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: avatar_not_found message: Avatar not found. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateAvatarLooksRequestBody: description: Request body for POST /v3/avatars/looks. discriminator: mapping: look_pack: $ref: '#/components/schemas/CreateLookPackLooksRequest' template: $ref: '#/components/schemas/CreateTemplateLooksRequest' propertyName: type oneOf: - $ref: '#/components/schemas/CreateLookPackLooksRequest' - $ref: '#/components/schemas/CreateTemplateLooksRequest' title: CreateAvatarLooksRequestBody CreateAvatarLooksResponse: description: Response for POST /v3/avatars/looks. properties: group_id: description: >- The avatar group the looks were added to. Pass it as the group_id filter of GET /v3/avatars/looks to list them all. title: Group Id type: string looks: description: The new looks, one per generated image, in output order. items: $ref: '#/components/schemas/CreatedLookRef' title: Looks type: array required: - group_id - looks title: CreateAvatarLooksResponse type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message CreateLookPackLooksRequest: additionalProperties: false description: >- Generate a Look Pack's looks into the avatar an existing look belongs to. properties: type: const: look_pack description: Generation method. 'look_pack' applies a Look Pack template. title: Type type: string reference_look_id: description: >- An existing avatar look used as the identity reference. The new looks are added to its avatar. maxLength: 128 minLength: 1 title: Reference Look Id type: string template_id: description: >- The Look Pack template to apply: a public template, or an enterprise custom pack assigned to your workspace. maxLength: 128 minLength: 1 title: Template Id type: string aspect_ratio: anyOf: - $ref: '#/components/schemas/LookPackAspectRatio' - type: 'null' default: null description: >- Output aspect ratio, '16:9' by default. Generation is always 16:9; '9:16' center-crops the delivered frames to portrait as the final step. required: - type - reference_look_id - template_id title: CreateLookPackLooksRequest type: object CreateTemplateLooksRequest: additionalProperties: false description: >- Restyle an existing avatar look into a single look template; the results are added to its avatar. properties: type: const: template description: >- Generation method. 'template' restyles the reference look into a single look template, producing two looks in the template's aspect ratio. title: Type type: string reference_look_id: description: >- An existing avatar look used as the identity reference. The new looks are added to its avatar. maxLength: 128 minLength: 1 title: Reference Look Id type: string template_id: description: >- 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. maxLength: 128 minLength: 1 title: Template Id type: string required: - type - reference_look_id - template_id title: CreateTemplateLooksRequest type: object CreatedLookRef: properties: id: description: >- 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). title: Id type: string required: - id title: CreatedLookRef type: object StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message LookPackAspectRatio: enum: - '16:9' - '9:16' title: LookPackAspectRatio type: string responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````