Skip to main content
POST
  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 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

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, 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. 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

Reference video

Public avatar with audio

Public avatar with text

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.

Authorizations

Authorization
string
header
required

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, and click to create a key.

Add it to the request header:

Body

application/json
model
enum<string>
required

HeyGen Avatar 6 model identifier

Available options:
heygen-avatar-6,
heygen-avatar-6-turbo
input
object
required

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.

callback_url
string<uri>

Webhook callback URL for result notifications

Example:

"https://your-domain.com/callback"

Response

Task submitted successfully

code
enum<integer>
required

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 for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required