Runnable examples for the HeyGen Avatar 6 API, a talking avatar API for HeyGen's Avatar 6 and Avatar 6 Turbo models, through PoYo's async video API: lip-synced talking videos in 1080p or 2K from a photo, a reference video of an animated character, or one of 1,248 HeyGen public avatars, driven by 2–60 seconds of audio or by text read in one of 102 listed voices.
Answer: To use the HeyGen Avatar 6 API, send a server-side request to POST https://api.poyo.ai/api/generate/submit with model heygen-avatar-6 (or heygen-avatar-6-turbo) and a PoYo API key, then poll GET https://api.poyo.ai/api/generate/status/{task_id} for the MP4 link. Pricing is pay-as-you-go per second of output, from 10 credits ($0.05) per second. The examples in this repository run with Python 3.9+, Node.js 22+, or cURL.
Last verified against the live PoYo schema and pricing on November 19, 2026.
- Model IDs:
heygen-avatar-6andheygen-avatar-6-turboonPOST https://api.poyo.ai/api/generate/submit - Released: November 17, 2026 by HeyGen; live on PoYo since November 19, 2026
- Output: one MP4 at 1080p (default) or 2K, 25 fps in PoYo tests; the video runs the length of the speech
- Inputs: a photo + audio; a reference video of an animated or illustrated character + audio; or a HeyGen public avatar + audio or up to 1,000 characters of text
- Speech: 2–60 seconds of audio up to 15 MB, or text read in one of 102 listed voices (default
Warm Pro Narrator) - Avatars and voices: 1,248 public avatar looks across 156 presenters, plus the 102 voices, listed on the Avatars and Voices page
- Aspect ratios: public avatar mode 16:9, 9:16, 1:1, 4:5, 5:4; photo and reference video modes keep the input's aspect ratio
- Pricing: pay-as-you-go per second of output with no subscription: from 10 credits ($0.05) per second with Avatar 6 Turbo at 1080p; Avatar 6 from 20 credits ($0.10) per second
- API key: one PoYo API key works for both model IDs
- Speed: Avatar 6 Turbo runs on HeyGen's accelerated inference stack for lower latency, according to HeyGen. In PoYo testing, a 4.9-second 1080p video from a photo finished in about 48 seconds
Real HeyGen Avatar 6 outputs generated through PoYo. The previews are silent GIFs; click one to open the MP4 with its speech.
Request: reference video (cartoon botanist, 1080p)
video_url: a 5-second clip of the character in a greenhouse
image_urls: a still image of the same character
audio_url: 8.3 seconds of speech — "Hi, I'm Juniper! I look after every plant in this greenhouse. Hand me a script and a voice, and I'll tell your story with a smile."
prompt: Cheerful and lively. Give a small wave on 'Hi', gesture toward the plants on 'this greenhouse', and smile warmly at the end.
Request: public avatar + text (Annie, 1080p)
avatar: Annie Sofa Sitting Front
voice: Ivy
aspect_ratio: 16:9
text: Hi, I'm Annie. Pick any of over twelve hundred HeyGen avatars, type your script, and choose a voice. A few minutes later, your presenter video is ready to share.
prompt: Warm, natural presenter energy. Smile on 'Hi', open one hand toward the camera on 'Pick any', and give a small nod on 'ready to share'.
Request: Avatar 6 Turbo public avatar + text (Abigail, 1080p)
avatar: Abigail Sofa Front
voice: Ivy
text: Welcome to our product walkthrough. Today I will show you how to turn a single script into a polished presenter video in just a few minutes. First, choose an avatar that fits your brand. Next, paste your script and pick a voice. Finally, press generate and share the finished video with your team.
HeyGen Avatar 6 is HeyGen's talking avatar video model, released on November 17, 2026, with a lower-latency Avatar 6 Turbo tier. It turns a speaker into a talking video with lip sync, facial expressions, and gestures: a photo of a person, a reference video of an animated or illustrated character, or one of HeyGen's public avatars. According to HeyGen, Avatar 6 changes gestures and expressions line by line to match the meaning of the speech, and accepts motion prompts that place an action on a specific word.
| HeyGen Avatar 6 | HeyGen Avatar 6 Turbo | |
|---|---|---|
| Model ID | heygen-avatar-6 |
heygen-avatar-6-turbo |
| HeyGen tier | Avatar 6 Quality | Avatar 6 Turbo, on HeyGen's accelerated inference stack |
| Input modes | Photo, reference video, public avatar | Same three modes |
| Resolution | 1080p (default), 2K | 1080p (default), 2K |
| Speech | 2–60 s audio, or up to 1,000 characters of text | Same limits |
| Price at 1080p | 20 credits ($0.10) per second | 10 credits ($0.05) per second |
| Price at 2K | 29 credits ($0.145) per second | 18 credits ($0.09) per second |
| 10-second 1080p video | 200 credits ($1.00) | 100 credits ($0.50) |
Both models take the same request fields, so switching tiers only means changing the model ID. Use Turbo for drafts, previews, and high-volume clips, and heygen-avatar-6 for final presenter and character videos.
- Create an API key in the PoYo dashboard. The same key works for
heygen-avatar-6andheygen-avatar-6-turbo. - Copy
.env.exampleto.envand replace the placeholder. - Run one of the examples. Each submits the task and polls until
finishedorfailed.
POYO_API_KEY=YOUR_POYO_API_KEY_HERE
POYO_BASE_URL=https://api.poyo.aipython python/generate.py
python python/generate.py payloads/heygen-avatar-6-turbo-avatar-text.jsonpython/generate.py uses only the Python standard library.
node node/index.mjs
node node/index.mjs payloads/heygen-avatar-6-reference-video.jsoncurl -X POST "https://api.poyo.ai/api/generate/submit" \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "heygen-avatar-6",
"input": {
"image_urls": ["https://storage.poyo.ai/models/heygen-avatar-6/examples/photo-mode-input-portrait-d62f53bee86e.png"],
"audio_url": "https://storage.poyo.ai/models/heygen-avatar-6/examples/photo-mode-input-speech-c00ad59e79d0.mp3",
"resolution": "1080p"
}
}'Status polling and the other modes are in curl/generate.md.
Every file in payloads/ is a complete request body with public input media, so it runs as-is. Audio requests are charged by the audio length rounded up; text requests by the finished video's length.
| File | Mode | Settings | Credits |
|---|---|---|---|
heygen-avatar-6-photo.json |
Photo + audio | Avatar 6, 1080p, 5.0 s audio | 100 ($0.50) |
heygen-avatar-6-reference-video.json |
Reference video + photo + audio | Avatar 6, 1080p, 8.3 s audio, motion prompt | 180 ($0.90) |
heygen-avatar-6-turbo-avatar-audio.json |
Public avatar + audio | Turbo, 1080p, 9:16, 5.0 s audio | 50 ($0.25) |
heygen-avatar-6-turbo-avatar-text.json |
Public avatar + text | Turbo, 1080p, 16:9, 297 characters, voice Ivy |
190 ($0.95) for an 18.2 s video |
The text request needs at least 330 credits in the balance at submission (1.5 times the estimated reading time); the final charge follows the finished video.
The supplied inputs select the mode automatically. Each request uses the inputs of one mode.
| Mode | Selected when | Inputs |
|---|---|---|
| Public avatar | avatar is provided |
avatar, plus audio_url or text (with an optional voice) |
| Reference video | video_url is provided |
video_url and audio_url, plus an optional reference photo in image_urls |
| Photo | By default | One photo in image_urls and audio_url |
Every mode also accepts prompt and resolution; aspect_ratio applies to public avatar mode. Reference video mode is made for animated and illustrated characters; for real people, use photo mode. Avatar and voice names are on the Avatars and Voices page, with a downloadable JSON list.
- Tie gestures to words: write the action next to the word, for example
Give a small wave on 'Hi', gesture toward the plants on 'this greenhouse', and smile warmly at the end. - Direct the body, not the words:
prompttakes up to 1,200 characters about gestures, expression, and posture; the speech comes fromaudio_urlortext. - Let the speech lead: without a prompt, Avatar 6 picks gestures that match the meaning of each line, such as pointing or counting, according to HeyGen.
- Size text scripts by time: about 300 characters of English produced 18.2–18.6 seconds of video in PoYo tests, and the charge follows the finished length.
- Draft, then render: iterate with
heygen-avatar-6-turboat 1080p, then switch the model ID toheygen-avatar-6and setresolutionto2Kfor the final cut.
More request examples are in the API reference.
| Field | Mode | Meaning |
|---|---|---|
| image_urls | Photo (required); reference video (optional) | Exactly one image: the person to animate, or a reference photo of the character. |
| video_url | Reference video (required) | A video of an animated or illustrated character, at least 2 seconds and up to 50 MB. |
| avatar | Public avatar (required) | One of 1,248 public avatar names, such as Abigail Sofa Front; matching ignores letter case and extra spaces. |
| audio_url | Photo and reference video (required); public avatar (or text) |
Speech audio, 2–60 seconds and up to 15 MB. The video runs the length of the audio. |
| text | Public avatar, in place of audio_url |
Up to 1,000 characters for the avatar to read aloud. |
| voice | Public avatar with text |
One of the 102 listed voices. Default Warm Pro Narrator. |
| prompt | All modes (optional) | Direction for gestures, expression, and posture, up to 1,200 characters. |
| aspect_ratio | Public avatar (optional) | 16:9, 9:16, 1:1, 4:5, or 5:4. Default 16:9. |
| resolution | All modes (optional) | 1080p or 2K. Default 1080p. |
HeyGen API pricing on PoYo is pay-as-you-go per second of output, with no subscription. 1 credit = $0.005.
| Model | 1080p | 2K |
|---|---|---|
heygen-avatar-6 |
20 credits ($0.10) per second | 29 credits ($0.145) per second |
heygen-avatar-6-turbo |
10 credits ($0.05) per second | 18 credits ($0.09) per second |
- With
audio_url(any mode), the charge is the audio length rounded up to whole seconds, taken when the task is submitted. - With
text(public avatar mode), submission needs credits for 1.5 times the estimated reading time, and the final charge is the finished video's length rounded up to whole seconds. In a production check on November 19, 2026, an Avatar 6 Turbo public avatar reading "Hi." returned a 1-second video, billed as 1 second (10 credits).
All three modes share the same rates. Confirm current prices on the model page before a production rollout.
| Clip length | Avatar 6 · 1080p | Avatar 6 · 2K | Turbo · 1080p | Turbo · 2K |
|---|---|---|---|---|
| 5 seconds | 100 credits ($0.50) | 145 credits ($0.725) | 50 credits ($0.25) | 90 credits ($0.45) |
| 10 seconds | 200 credits ($1.00) | 290 credits ($1.45) | 100 credits ($0.50) | 180 credits ($0.90) |
| 30 seconds | 600 credits ($3.00) | 870 credits ($4.35) | 300 credits ($1.50) | 540 credits ($2.70) |
A full 60-second clip costs 600 credits ($3.00) with Turbo at 1080p and 1,200 credits ($6.00) with Avatar 6 at 1080p. Failed generation tasks are not charged credits.
submit -> persist data.task_id -> poll during development -> receive callback_url webhook in production
Treat finished and failed as terminal states. Accept a webhook only for task IDs your system created, process it idempotently, and reconcile the final state through the status endpoint. Copy output videos to your own storage after the task finishes.
Always read code in the response body: parameter errors return HTTP 200 with code: 400.
code |
error.type |
Example and fix |
|---|---|---|
| 400 | validation_error |
avatar "Abigail Garden Front" was not found. Closest matches: "Abigail Sofa Front", "Abigail Office Front", ...: pick a name from the avatar list. |
| 400 | validation_error |
audio_url could not be accessed. Please make sure the link is valid and publicly accessible.: use a public, directly downloadable link. |
| 400 | content_moderation_error |
The prompt or media was declined by safety review: revise and submit a new task. |
| 401 | authentication_error |
Missing or invalid key: send Authorization: Bearer <POYO_API_KEY>. |
| 402 | insufficient_credits_error |
Insufficient credits: this request needs at least 20 credits.: top up in the dashboard. Text requests reserve credits for unfinished text tasks, and the message shows the amount already reserved. |
| 429 | rate_limit_error |
Back off and retry. |
A task that fails after submission returns status: "failed" with error_message, and is not charged credits. Messages seen in PoYo testing:
The selected voice is not available. Please check the voice name and try again.: use one of the 102 listed voice names.The image URL could not be accessed. Please make sure the link is valid and publicly accessible.: host the photo at a public, directly downloadable URL.
See error codes.
What is HeyGen Avatar 6? HeyGen's talking avatar video model, released on November 17, 2026. It animates a photo, a cartoon or illustrated character video, or a HeyGen public avatar into a lip-synced talking video in 1080p or 2K, with gestures matched to the speech. PoYo offers heygen-avatar-6 and the lower-latency heygen-avatar-6-turbo.
Is there a HeyGen API for Avatar 6? Yes. HeyGen offers Avatar 6 through its own HeyGen API, and on PoYo you call it with POST https://api.poyo.ai/api/generate/submit and the model ID heygen-avatar-6 or heygen-avatar-6-turbo, then read the result from the status endpoint or a callback_url. The same request format covers the other video models on PoYo.
How do I get a HeyGen Avatar 6 API key? Create a PoYo account, open API Keys in the dashboard, and create a key. Add credits, then send the key as Authorization: Bearer <POYO_API_KEY>. One key works for both HeyGen Avatar 6 model IDs.
How much does the HeyGen Avatar 6 API cost? Avatar 6 costs 20 credits ($0.10) per second at 1080p and 29 credits ($0.145) at 2K; Avatar 6 Turbo costs 10 credits ($0.05) and 18 credits ($0.09). With audio, the charge is the audio length rounded up; with text, the finished video's length rounded up. A 10-second 1080p Turbo video costs 100 credits ($0.50).
Is the HeyGen Avatar 6 API free? It is pay-as-you-go with no subscription: you pay only for the seconds you generate, and failed tasks are not charged. A 1-second Turbo clip costs 10 credits ($0.05), so a first test costs only a few cents. You can also try both models in the Playground before writing code.
What is the difference between Avatar 6 and Avatar 6 Turbo? Both take the same inputs, limits, avatars, and voices and output 1080p or 2K. Avatar 6 is HeyGen's Quality tier; Avatar 6 Turbo runs on HeyGen's accelerated inference stack for lower latency, according to HeyGen, and costs half at 1080p. Start with Turbo for drafts and switch the model ID for final renders.
How do I turn a photo into a talking video? Send one photo of the person in image_urls and 2–60 seconds of speech, up to 15 MB, in audio_url. The talking photo video runs as long as the audio and keeps the photo's aspect ratio. In a PoYo test, a square photo with 5 seconds of audio returned a 1088×1088 1080p video in about 48 seconds. To start from a script, create the speech with a text-to-speech model such as ElevenLabs V3 TTS, or use a public avatar with text.
Can the HeyGen Avatar 6 API animate cartoon or illustrated characters? Yes. Reference video mode is made for them: send a clip of the character, at least 2 seconds and up to 50 MB, in video_url, speech in audio_url, and optionally a still of the same character in image_urls. The output keeps the clip's aspect ratio.
Which public avatars and voices can I use? 1,248 HeyGen public avatar looks across 156 presenters, such as Abigail Sofa Front or Annie Sofa Sitting Front, and 102 listed voices for text, such as Warm Pro Narrator (the default), Ivy, or Chill Brian. Names match regardless of letter case and extra spaces. The full lists, with a downloadable JSON file, are on the Avatars and Voices page.
How do I call the HeyGen Avatar 6 API from Python? Set POYO_API_KEY and run python python/generate.py with a file from payloads/. The script uses only the standard library: it submits the request, polls the status endpoint every 5 seconds, and prints the final response, where data.files[0].file_url is the MP4 to download. The Node.js and cURL versions follow the same steps.
How long can a video be? With audio, each video runs as long as the audio, from 2 to 60 seconds, and the clip is about 0.1–0.2 seconds shorter than the audio. With text, the length follows the reading time of up to 1,000 characters; about 300 characters of English produced 18.2–18.6 seconds of video in PoYo tests.
How long does a generation take? In PoYo test runs, photo and reference video tasks finished in about 45 seconds to 3 minutes, and public avatar tasks in about 1 to 4 minutes, depending on length, resolution, and load. Use callback_url or poll the task status instead of waiting on the request.
How is HeyGen Avatar 6 different from Avatar V? According to HeyGen, Avatar 6 reads the script and gestures to match it, with more realistic lip sync, native 2K frames, and motion prompts that place an action on a specific word, and it adds the lower-latency Turbo tier. The HeyGen Avatar 6 API on PoYo offers both tiers through one request format.
How does HeyGen Avatar 6 compare with OmniHuman 2.0 on PoYo? Both animate a portrait with audio. HeyGen Avatar 6 outputs 1080p or 2K from 2–60 seconds of audio and adds public avatars that read text, a reference video mode for animated characters, and word-level motion prompts. OmniHuman 2.0 (omnihuman-2.0) outputs 720p from 4–300 seconds of speech or singing and suits longer speeches and songs.
payloads/— complete request bodies for each modepython/generate.py— standard-library Python examplenode/index.mjs— dependency-free Node.js examplecurl/generate.md— copy-paste cURL requestsdocs/production-notes.md— limits, billing, and rollout checklist
- Kling-Avatar-2.0-API — Kling Avatar 2.0 talking-avatar examples
- ElevenLabs-V3-TTS-API — create speech audio for
audio_url - poyo-examples — examples across PoYo models
- poyo-devtools — PoYo CLI, MCP bridge, and Agent Skill (MCP tools
poyo_heygen_avatar_6andpoyo_heygen_avatar_6_turbo)
- HeyGen Avatar 6 API on PoYo
- HeyGen Avatar 6 API reference
- HeyGen Avatar 6 avatars and voices
- PoYo model catalog
MIT