curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}HeyGen
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.
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the response result through the unified Query Task Status endpoint.
Models
- heygen-avatar-6 — Talking avatar video at
1080por2Kin 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
textand an optionalvoice, and the avatar reads the text aloud. - Motion direction: Use
promptto guide gestures, expression, and posture. - Output:
1080por2K. Public avatar videos use16:9,9:16,1:1,4:5, or5: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 |
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 asAbigail 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, sendaudio_urlortext. 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 ofaudio_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 withtext. 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, or5:4. Default:16:9. In photo and reference video modes, the video keeps the aspect ratio of the input photo or video.resolution(string):1080por2K. 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 readtext. The video can be about a tenth of a second shorter than the audio.
Examples
Photo
{
"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
{
"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
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Public avatar with text
{
"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.
avataris checked against the avatar list when the task is submitted.
Authorizations
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:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Response
Task submitted successfully
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: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200