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

# HeyGen Avatar 6

> The HeyGen Avatar 6 API creates a lip-synced talking video at 1080p or 2K from a photo, a reference video of an animated character, or a HeyGen public avatar, driven by 2–60 seconds of audio or, for public avatars, by text.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

HeyGen Avatar 6 turns a speaker into a talking video with lip sync, facial expressions, and natural gestures. Animate a photo of a person, an animated or illustrated character from a reference video, or one of HeyGen's public avatars. The speech comes from an audio file, or, with a public avatar, from text read aloud by a HeyGen voice. The supplied inputs select the mode automatically.

## Models

* **heygen-avatar-6** — Talking avatar video at `1080p` or `2K` in photo, reference video, and public avatar modes
* **heygen-avatar-6-turbo** — Turbo tier of Avatar 6 with the same inputs and modes

## Features

* **Three input modes**: A photo of a person, a reference video of an animated or illustrated character, or a HeyGen public avatar.
* **Audio-driven length**: The video runs the length of the speech audio, from 2 to 60 seconds.
* **Text to speech for public avatars**: Send `text` and an optional `voice`, and the avatar reads the text aloud.
* **Motion direction**: Use `prompt` to guide gestures, expression, and posture.
* **Output**: `1080p` or `2K`. Public avatar videos use `16:9`, `9:16`, `1:1`, `4:5`, or `5:4`.

## Input modes

| Mode | Selected when | Inputs |
| - | - | - |
| Public avatar | `avatar` is provided | `avatar`, plus `audio_url` or `text` |
| Reference video | `video_url` is provided | `video_url` and `audio_url`, plus an optional reference photo in `image_urls` |
| Photo | By default | `image_urls` and `audio_url` |

Each mode accepts the inputs listed in its row and the shared options `prompt` and `resolution`. `aspect_ratio` and `voice` belong to public avatar mode. Use the inputs of one mode in each request.

## Required parameters

* `image_urls` (array of strings): Photo mode. Exactly one photo of the person to animate; `image_urls[0]` is used.
* `video_url` (string): Reference video mode. A video of an animated or illustrated character, at least 2 seconds long and up to 50 MB.
* `avatar` (string): Public avatar mode. The name of one of the 1,248 HeyGen public avatars listed in [Avatars and Voices](https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-avatars.md), such as `Abigail Sofa Front`. Names match regardless of letter case and extra spaces.
* `audio_url` (string): Speech audio for photo and reference video modes. In public avatar mode, send `audio_url` or `text`. The audio must be 2–60 seconds long and up to 15 MB; the video runs the length of the audio.
* `text` (string): Public avatar mode, in place of `audio_url`. The text the avatar reads aloud, up to 1,000 characters.

## Optional parameters

* `image_urls` (array of strings): Reference video mode. One reference photo of the same character.
* `voice` (string): Public avatar mode with `text`. The HeyGen voice that reads the text: one of the 102 voices in [Avatars and Voices](https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-avatars.md#voices). Names match regardless of letter case and extra spaces. Default: `Warm Pro Narrator`.
* `prompt` (string): Direction for the avatar's gestures, expression, and posture, up to 1,200 characters.
* `aspect_ratio` (string): Public avatar mode. `16:9`, `9:16`, `1:1`, `4:5`, or `5:4`. Default: `16:9`. In photo and reference video modes, the video keeps the aspect ratio of the input photo or video.
* `resolution` (string): `1080p` or `2K`. Default: `1080p`.

## Output

* One MP4 video file.
* The video length follows the speech: the duration of `audio_url`, or the time the avatar takes to read `text`. The video can be about a tenth of a second shorter than the audio.

## Examples

### Photo

```json theme={"dark"}
{
  "model": "heygen-avatar-6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "image_urls": ["https://example.com/presenter.png"],
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
    "resolution": "1080p"
  }
}
```

### Reference video

```json theme={"dark"}
{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "video_url": "https://example.com/cartoon-character.mp4",
    "image_urls": ["https://example.com/cartoon-character.png"],
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "2K"
  }
}
```

### Public avatar with audio

```json theme={"dark"}
{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}
```

### Public avatar with text

```json theme={"dark"}
{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "avatar": "Abigail Office Front",
    "text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
    "voice": "Warm Pro Narrator",
    "prompt": "Speak with calm confidence and nod slightly at the end.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}
```

## Notes

* All media URLs must be publicly accessible over HTTP or HTTPS and directly downloadable.
* Audio length and the reference video length are checked when the task is submitted.
* `avatar` is checked against the avatar list when the task is submitted.


## OpenAPI

````yaml api-manual/video-series/heygen-avatar-6.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - HeyGen Avatar 6 API
  description: >-
    The HeyGen Avatar 6 API creates a lip-synced talking video at 1080p or 2K
    from a photo, a reference video of an animated character, or a HeyGen public
    avatar, driven by 2–60 seconds of audio or, for public avatars, by text.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - HeyGen Avatar 6
      summary: Submit HeyGen Avatar 6 Task
      description: >-
        Create a talking avatar video from a photo, a reference video of an
        animated or illustrated character, or a HeyGen public avatar.
      operationId: submitHeygenAvatar6Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              photo:
                summary: Photo
                value:
                  model: heygen-avatar-6
                  callback_url: https://your-domain.com/callback
                  input:
                    image_urls:
                      - https://example.com/presenter.png
                    audio_url: https://example.com/speech.mp3
                    prompt: >-
                      Face the camera with a warm smile and use small, natural
                      hand gestures.
                    resolution: 1080p
              reference-video:
                summary: Reference video
                value:
                  model: heygen-avatar-6-turbo
                  input:
                    video_url: https://example.com/cartoon-character.mp4
                    image_urls:
                      - https://example.com/cartoon-character.png
                    audio_url: https://example.com/speech.mp3
                    resolution: 2K
              avatar-audio:
                summary: Public avatar with audio
                value:
                  model: heygen-avatar-6
                  input:
                    avatar: Abigail Sofa Front
                    audio_url: https://example.com/speech.mp3
                    aspect_ratio: '9:16'
              avatar-text:
                summary: Public avatar with text
                value:
                  model: heygen-avatar-6-turbo
                  input:
                    avatar: Abigail Office Front
                    text: >-
                      Hello and welcome to this demonstration of HeyGen Avatar
                      6.
                    voice: Warm Pro Narrator
                    prompt: Speak with calm confidence and nod slightly at the end.
                    aspect_ratio: '16:9'
                    resolution: 1080p
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: HeyGen Avatar 6 model identifier
          enum:
            - heygen-avatar-6
            - heygen-avatar-6-turbo
        callback_url:
          type: string
          format: uri
          description: Webhook callback URL for result notifications
          example: https://your-domain.com/callback
        input:
          type: object
          additionalProperties: false
          description: >-
            The supplied inputs select the mode: `avatar` selects public avatar
            mode, otherwise `video_url` selects reference video mode, otherwise
            photo mode is used. Use the inputs of one mode in each request.
          properties:
            image_urls:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                format: uri
              description: >-
                Exactly one image. Required in photo mode: a photo of the person
                to animate. Optional in reference video mode: a reference photo
                of the same character. Publicly accessible HTTP or HTTPS URL;
                `image_urls[0]` is used.
              example:
                - https://example.com/presenter.png
            video_url:
              type: string
              format: uri
              description: >-
                Required in reference video mode. A video of an animated or
                illustrated character, at least 2 seconds long and up to 50 MB.
                Publicly accessible HTTP or HTTPS URL.
              example: https://example.com/cartoon-character.mp4
            avatar:
              type: string
              minLength: 1
              description: >-
                Required in public avatar mode. The name of one of the 1,248
                HeyGen public avatars listed in [Avatars and
                Voices](/api-manual/video-series/heygen-avatar-6-avatars), such
                as `Abigail Sofa Front`. Names match regardless of letter case
                and extra spaces.
              example: Abigail Sofa Front
            audio_url:
              type: string
              format: uri
              description: >-
                Speech audio, 2–60 seconds long and up to 15 MB. Required in
                photo and reference video modes. In public avatar mode, send
                `audio_url` or `text`. The video runs the length of the audio.
                Publicly accessible HTTP or HTTPS URL.
              example: https://example.com/speech.mp3
            text:
              type: string
              minLength: 1
              maxLength: 1000
              description: >-
                Public avatar mode, in place of `audio_url`. The text the avatar
                reads aloud, up to 1,000 characters.
              example: Hello and welcome to this demonstration of HeyGen Avatar 6.
            voice:
              type: string
              minLength: 1
              default: Warm Pro Narrator
              description: >-
                Public avatar mode with `text`. The HeyGen voice that reads the
                text: one of the 102 voices in [Avatars and
                Voices](/api-manual/video-series/heygen-avatar-6-avatars#voices).
                Names match regardless of letter case and extra spaces. Default:
                `Warm Pro Narrator`.
              example: Warm Pro Narrator
            prompt:
              type: string
              maxLength: 1200
              description: >-
                Direction for the avatar's gestures, expression, and posture, up
                to 1,200 characters.
              example: >-
                Face the camera with a warm smile and use small, natural hand
                gestures.
            aspect_ratio:
              type: string
              enum:
                - '16:9'
                - '9:16'
                - '1:1'
                - '4:5'
                - '5:4'
              default: '16:9'
              description: >-
                Public avatar mode. Output aspect ratio. Default: `16:9`. In
                photo and reference video modes, the video keeps the aspect
                ratio of the input photo or video.
              example: '16:9'
            resolution:
              type: string
              enum:
                - 1080p
                - 2K
              default: 1080p
              description: 'Output resolution. Default: `1080p`.'
              example: 1080p
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2025-11-12T10:30:00'
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication.


        Create an API key: sign in to PoYo, open **Dashboard → API Key** at
        [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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