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

# Create Avatar 6 Video

> Animates a reference image or video with driving speech audio using Avatar 6 (`heygen-avatar-6` or `heygen-avatar-6-turbo`). Provide one reference image or one reference video, plus `audio`. Optionally direct the performance with `motion_prompt` or `motion_expressiveness`. Returns 202 with a `video_id`; poll GET /v3/models/videos/{video_id}. Send an Idempotency-Key to retry safely. To have a saved avatar look speak a script, use POST /v3/videos.



## OpenAPI

````yaml /openapi/external-api.json post /v3/models/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
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/models/avatars:
    post:
      tags:
        - Avatar
      summary: Create Avatar 6 Video
      description: >-
        Animates a reference image or video with driving speech audio using
        Avatar 6 (`heygen-avatar-6` or `heygen-avatar-6-turbo`). Provide one
        reference image or one reference video, plus `audio`. Optionally direct
        the performance with `motion_prompt` or `motion_expressiveness`. Returns
        202 with a `video_id`; poll GET /v3/models/videos/{video_id}. Send an
        Idempotency-Key to retry safely. To have a saved avatar look speak a
        script, use POST /v3/videos.
      operationId: createModelAvatarVideo
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelAvatarRequest'
      responses:
        '202':
          description: Accepted — submission acknowledged; poll for completion.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateModelAvatarResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: Value error, Provide at least one reference image or video.
                  param: null
                  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
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: forbidden
                  message: forbidden
                  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: asset_not_found
                  message: Asset not found.
                  param: null
                  doc_url: null
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '422':
          description: >-
            Graph invalid — the request parsed but the workflow graph is
            semantically invalid; `error.errors[]` lists every issue found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: realistic_human_reference_not_allowed
                  message: >-
                    Using videos of realistic humans as references requires
                    identity verification. Create your avatar in HeyGen, then
                    use the /v3/videos API to create your video. For enterprise
                    access, contact our sales team at
                    https://www.heygen.com/contact-us/sales.
                  param: reference_videos
                  doc_url: null
        '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
        '503':
          description: >-
            Temporarily unavailable — the request did not complete and is safe
            to retry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Reference video screening is unavailable. Retry the request
                    shortly.
                  param: reference_videos
                  doc_url: null
      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:
    CreateModelAvatarRequest:
      properties:
        model:
          description: Avatar generation model.
          enum:
            - heygen-avatar-6
            - heygen-avatar-6-turbo
          title: Model
          type: string
        reference_images:
          description: Up to one reference image.
          items:
            discriminator:
              mapping:
                asset_id: '#/components/schemas/AssetId'
                base64: '#/components/schemas/AssetBase64'
                url: '#/components/schemas/AssetUrl'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/AssetUrl'
              - $ref: '#/components/schemas/AssetId'
              - $ref: '#/components/schemas/AssetBase64'
          maxItems: 1
          title: Reference Images
          type: array
        reference_videos:
          description: >-
            Up to one reference video, at least 2 seconds long. A shorter video
            returns HTTP 400 (invalid_parameter) before a job is created.
          items:
            discriminator:
              mapping:
                asset_id: '#/components/schemas/AssetId'
                base64: '#/components/schemas/AssetBase64'
                url: '#/components/schemas/AssetUrl'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/AssetUrl'
              - $ref: '#/components/schemas/AssetId'
              - $ref: '#/components/schemas/AssetBase64'
          maxItems: 1
          title: Reference Videos
          type: array
        audio:
          description: Driving speech audio.
          discriminator:
            mapping:
              asset_id: '#/components/schemas/AssetId'
              base64: '#/components/schemas/AssetBase64'
              url: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: Audio
        resolution:
          default: 1080p
          description: Inference resolution. Defaults to 1080p.
          enum:
            - 1080p
            - 2k
          title: Resolution
          type: string
        motion_prompt:
          anyOf:
            - maxLength: 1200
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Optional instructions for gestures, expression, posture, and camera
            behavior. Overrides motion_expressiveness where specified.
          title: Motion Prompt
        motion_expressiveness:
          default: default
          description: >-
            Use default for the model's usual motion, or less for fewer and
            smaller gestures and calmer facial expressions. Does not disable
            motion.
          enum:
            - default
            - less
          title: Motion Expressiveness
          type: string
        output_width:
          anyOf:
            - exclusiveMinimum: 0
              multipleOf: 2
              type: integer
            - type: 'null'
          default: null
          description: >-
            Output width in pixels; supply with output_height, or omit both to
            use the native size.
          title: Output Width
        output_height:
          anyOf:
            - exclusiveMinimum: 0
              multipleOf: 2
              type: integer
            - type: 'null'
          default: null
          description: >-
            Output height in pixels; supply with output_width, or omit both to
            use the native size.
          title: Output Height
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: HTTPS URL for terminal generation notifications.
          title: Callback Url
        callback_id:
          anyOf:
            - maxLength: 256
              type: string
            - type: 'null'
          default: null
          description: Client identifier echoed in terminal notifications.
          title: Callback Id
      required:
        - model
        - audio
      title: CreateModelAvatarRequest
      type: object
    CreateModelAvatarResponse:
      properties:
        video_id:
          description: Video identifier for polling.
          title: Video Id
          type: string
        status:
          const: pending
          default: pending
          description: Generation has been accepted.
          title: Status
          type: string
      required:
        - video_id
      title: CreateModelAvatarResponse
      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'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    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 an asset upload or import; not a third-party
            file ID.
          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: >-
            Public http(s) URL HeyGen can download without auth or redirects.
            Not a local or sandbox path (/mnt/data/..., file://, sandbox:);
            upload such files and pass asset_id.
          title: Url
          type: string
      required:
        - type
        - url
      title: AssetUrl
      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
  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.

````

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