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

# Create Avatar

> Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.



## OpenAPI

````yaml /openapi/external-api.json post /v3/avatars
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: 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: User
    description: Account information and billing
  - 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)
paths:
  /v3/avatars:
    post:
      tags:
        - Avatars
      summary: Create Avatar
      description: >-
        Creates a new avatar from an image, video footage, or a text prompt.
        Supports photo, digital_twin, and prompt types. Avatar training is
        asynchronous.
      operationId: createAvatar
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAvatarRequestBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateAvatarResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: >-
                    At least one file source is required: provide image, video,
                    or consent_video.
                  param: files
                  doc_url: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: authentication_failed
                  message: Invalid or expired API key. Verify your x-api-key header.
                  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:
    CreateAvatarRequestBody:
      description: Discriminated union for POST /v3/avatars request body.
      discriminator:
        mapping:
          digital_twin:
            $ref: '#/components/schemas/CreateDigitalTwinRequest'
          photo:
            $ref: '#/components/schemas/CreatePhotoAvatarRequest'
          prompt:
            $ref: '#/components/schemas/CreatePromptAvatarRequest'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/CreatePromptAvatarRequest'
        - $ref: '#/components/schemas/CreateDigitalTwinRequest'
        - $ref: '#/components/schemas/CreatePhotoAvatarRequest'
      title: CreateAvatarRequestBody
    CreateAvatarResponse:
      properties:
        avatar_item:
          anyOf:
            - $ref: '#/components/schemas/AvatarLookItem'
            - type: 'null'
          default: null
          description: The avatar item.
        avatar_group:
          anyOf:
            - $ref: '#/components/schemas/AvatarGroupItem'
            - type: 'null'
          default: null
          description: The avatar group.
      title: CreateAvatarResponse
      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
      required:
        - code
        - message
    CreateDigitalTwinRequest:
      properties:
        type:
          const: digital_twin
          description: Must be 'digital_twin' for digital twin avatars.
          title: Type
          type: string
        name:
          description: Name of the avatar.
          title: Name
          type: string
        file:
          description: >-
            Footage of the avatar — provide as {"type": "url", "url":
            "https://..."} or {"type": "asset_id", "asset_id": "..."}
          discriminator:
            mapping:
              asset_id:
                $ref: '#/components/schemas/AssetId'
              base64:
                $ref: '#/components/schemas/AssetBase64'
              url:
                $ref: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: File
        avatar_group_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional identity you would like to attach the digital twin to. By
            default it will create a new identity.
          title: Avatar Group Id
      required:
        - type
        - name
        - file
      title: CreateDigitalTwinRequest
      type: object
    CreatePhotoAvatarRequest:
      properties:
        type:
          const: photo
          description: Must be 'photo' for photo-based avatars.
          title: Type
          type: string
        name:
          description: Name of the avatar.
          title: Name
          type: string
        file:
          description: >-
            Photo asset of the avatar — provide as {"type": "url", "url":
            "https://..."} or {"type": "asset_id", "asset_id": "..."}
          discriminator:
            mapping:
              asset_id:
                $ref: '#/components/schemas/AssetId'
              base64:
                $ref: '#/components/schemas/AssetBase64'
              url:
                $ref: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: File
        avatar_group_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional identity you would like to attach the photo avatar to. By
            default it will create a new identity.
          title: Avatar Group Id
      required:
        - type
        - name
        - file
      title: CreatePhotoAvatarRequest
      type: object
    CreatePromptAvatarRequest:
      properties:
        type:
          const: prompt
          description: Must be 'prompt' for AI-generated avatars.
          title: Type
          type: string
        name:
          description: Name of the avatar.
          title: Name
          type: string
        prompt:
          description: Prompt for avatar generation.
          maxLength: 1000
          title: Prompt
          type: string
        reference_images:
          anyOf:
            - items:
                discriminator:
                  mapping:
                    asset_id:
                      $ref: '#/components/schemas/AssetId'
                    base64:
                      $ref: '#/components/schemas/AssetBase64'
                    url:
                      $ref: '#/components/schemas/AssetUrl'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/AssetUrl'
                  - $ref: '#/components/schemas/AssetId'
                  - $ref: '#/components/schemas/AssetBase64'
              maxItems: 3
              type: array
            - type: 'null'
          default: null
          description: >-
            Reference images — each as {"type": "url", "url": "https://..."} or
            {"type": "asset_id", "asset_id": "..."}. Max 3. Will only work with
            an avatar_group_id.
          title: Reference Images
        avatar_group_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional identity you would like to attach the prompted avatar to.
            By default it will create a new identity.
          title: Avatar Group Id
      required:
        - type
        - name
        - prompt
      title: CreatePromptAvatarRequest
      type: object
    AvatarLookItem:
      description: |-
        A single avatar look in the list response.

        The ``id`` field is the look-level identifier to pass as ``avatar_id``
        to POST /v3/videos.
      properties:
        id:
          description: Unique look identifier. Pass this as avatar_id to POST /v3/videos.
          examples:
            - lk_abc123
          title: Id
          type: string
        name:
          description: Display name of the look.
          examples:
            - Business Suit
          title: Name
          type: string
        avatar_type:
          $ref: '#/components/schemas/AvatarLookType'
          description: Avatar type — determines engine and parameter compatibility.
          examples:
            - photo_avatar
        group_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: ID of the avatar group this look belongs to.
          examples:
            - ag_abc123
          title: Group Id
        preview_image_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: URL to the look preview image.
          examples:
            - https://files.heygen.ai/look/business_preview.jpg
          title: Preview Image Url
        preview_video_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: URL to the look preview video.
          examples:
            - https://files.heygen.ai/look/business_preview.mp4
          title: Preview Video Url
        gender:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Gender of the avatar.
          examples:
            - female
          title: Gender
        tags:
          description: Tags associated with the look.
          examples:
            - - business
              - formal
          items:
            type: string
          title: Tags
          type: array
        default_voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Default voice ID for this look.
          examples:
            - 1bd001e7e50f421d891986aad5c8bbd2
          title: Default Voice Id
        supported_api_engines:
          description: Engine values this look supports for POST /v3/videos.
          examples:
            - - avatar_v
              - avatar_iv
          items:
            type: string
          title: Supported Api Engines
          type: array
        image_width:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Native width of the look in pixels.
          examples:
            - 1920
          title: Image Width
        image_height:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Native height of the look in pixels.
          examples:
            - 1080
          title: Image Height
        preferred_orientation:
          anyOf:
            - enum:
                - portrait
                - landscape
                - square
              type: string
            - type: 'null'
          default: null
          description: >-
            Preferred orientation of the look: 'portrait', 'landscape', or
            'square'.
          title: Preferred Orientation
        status:
          anyOf:
            - $ref: '#/components/schemas/AvatarStatus'
            - type: 'null'
          default: null
          description: >-
            Training status of the avatar look: 'processing', 'completed', or
            'failed'. Only present for private avatars.
          examples:
            - completed
        error:
          anyOf:
            - $ref: '#/components/schemas/AvatarError'
            - type: 'null'
          default: null
          description: Error details. Only present when status is 'failed'.
      required:
        - id
        - name
        - avatar_type
      title: AvatarLookItem
      type: object
    AvatarGroupItem:
      description: >-
        A single avatar group in the list response.


        Groups are containers for looks (outfits/styles). To determine avatar
        type

        and engine compatibility, fetch the looks via GET /v3/avatars/looks.
      properties:
        id:
          description: Unique avatar group identifier.
          examples:
            - ag_abc123
          title: Id
          type: string
        name:
          description: Display name of the avatar.
          examples:
            - Anna
          title: Name
          type: string
        preview_image_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: URL to the avatar preview image.
          examples:
            - https://files.heygen.ai/avatar/anna_preview.jpg
          title: Preview Image Url
        preview_video_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: URL to the avatar preview video.
          examples:
            - https://files.heygen.ai/avatar/anna_preview.mp4
          title: Preview Video Url
        gender:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Gender of the avatar.
          examples:
            - female
          title: Gender
        created_at:
          description: Unix timestamp (seconds) when the avatar was created.
          examples:
            - 1711929600
          title: Created At
          type: integer
        looks_count:
          description: Number of looks (outfits/styles) available for this avatar.
          examples:
            - 3
          title: Looks Count
          type: integer
        default_voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Default voice ID for this avatar.
          examples:
            - 1bd001e7e50f421d891986aad5c8bbd2
          title: Default Voice Id
        consent_status:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            The status of consent for the group. None means consent is not
            required.
          examples:
            - approved
          title: Consent Status
        status:
          anyOf:
            - $ref: '#/components/schemas/AvatarStatus'
            - type: 'null'
          default: null
          description: >-
            Training status of the avatar group. Only present for private
            avatars.
          examples:
            - completed
        error:
          anyOf:
            - $ref: '#/components/schemas/AvatarError'
            - type: 'null'
          default: null
          description: Error details. Only present when status is 'failed'.
      required:
        - id
        - name
        - created_at
        - looks_count
      title: AvatarGroupItem
      type: object
    AssetId:
      additionalProperties: false
      description: Asset input via HeyGen asset ID from the asset upload endpoint.
      properties:
        type:
          const: asset_id
          description: Input type discriminator
          title: Type
          type: string
        asset_id:
          description: HeyGen asset ID from the asset upload endpoint
          title: Asset Id
          type: string
      required:
        - type
        - asset_id
      title: AssetId
      type: object
    AssetBase64:
      additionalProperties: false
      description: Asset input via base64-encoded content.
      properties:
        type:
          const: base64
          description: Input type discriminator
          title: Type
          type: string
        media_type:
          description: MIME type of the encoded content (e.g. "image/png")
          title: Media Type
          type: string
        data:
          description: Base64-encoded file content
          title: Data
          type: string
      required:
        - type
        - media_type
        - data
      title: AssetBase64
      type: object
      x-mcp-visible: false
    AssetUrl:
      additionalProperties: false
      description: Asset input via publicly accessible HTTPS URL.
      properties:
        type:
          const: url
          description: Input type discriminator
          title: Type
          type: string
        url:
          description: Publicly accessible HTTPS URL for the asset
          title: Url
          type: string
      required:
        - type
        - url
      title: AssetUrl
      type: object
    AvatarLookType:
      description: Avatar look type — determines engine compatibility with POST /v3/videos.
      enum:
        - studio_avatar
        - digital_twin
        - photo_avatar
      title: AvatarLookType
      type: string
    AvatarStatus:
      description: Training/creation status of an avatar group or look.
      enum:
        - processing
        - pending_consent
        - failed
        - completed
      title: AvatarStatus
      type: string
    AvatarError:
      description: Error details for a failed avatar creation.
      properties:
        code:
          description: Machine-readable error code.
          examples:
            - training_failed
          title: Code
          type: string
        message:
          description: Human-readable error description.
          examples:
            - Footage duration must be between 15s and 600s
          title: Message
          type: string
      required:
        - code
        - message
      title: AvatarError
      type: object
  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.

````