Skip to content

About

HeyGen Avatar 6 API examples in cURL, Python, and Node.js: a talking avatar API for heygen-avatar-6 and heygen-avatar-6-turbo. Turn a photo, an animated character video, or a HeyGen public avatar into a lip-synced 1080p or 2K video.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

HeyGen Avatar 6 API: cURL, Python, and Node.js Examples

HeyGen Avatar 6 on PoYo API docs Check

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.

HeyGen Avatar 6 at a glance

  • Model IDs: heygen-avatar-6 and heygen-avatar-6-turbo on POST 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

HeyGen Avatar 6 API examples (video)

Real HeyGen Avatar 6 outputs generated through PoYo. The previews are silent GIFs; click one to open the MP4 with its speech.

HeyGen Avatar 6 API photo-to-talking-video example: a man in a suit speaks to the camera on a neon-lit city street
Photo + audio · Avatar 6 · 1080p · 4.9 s · 120 credits
The portrait and speech of payloads/heygen-avatar-6-photo.json (a 5.04 s take, billed as 6 s); 1088×1088 output
HeyGen Avatar 6 API reference video example: a cartoon botanist in a greenhouse speaks and waves
Reference video + audio · Avatar 6 · 1080p · 8.2 s · 180 credits
The output of payloads/heygen-avatar-6-reference-video.json
HeyGen Avatar 6 API public avatar example: Annie Sofa Sitting Front reads a short script in the Ivy voice
Public avatar + text · Avatar 6 · 1080p · 10.8 s · 220 credits
Annie Sofa Sitting Front, voice Ivy, with a motion prompt
HeyGen Avatar 6 Turbo API example: Abigail Sofa Front presents a product walkthrough script
Public avatar + text · Avatar 6 Turbo · 1080p · 18.2 s · 190 credits
The output of payloads/heygen-avatar-6-turbo-avatar-text.json (preview shows the first 9 s)
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.

What is HeyGen Avatar 6?

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.

HeyGen Avatar 6 API quickstart

  1. Create an API key in the PoYo dashboard. The same key works for heygen-avatar-6 and heygen-avatar-6-turbo.
  2. Copy .env.example to .env and replace the placeholder.
  3. Run one of the examples. Each submits the task and polls until finished or failed.
POYO_API_KEY=YOUR_POYO_API_KEY_HERE
POYO_BASE_URL=https://api.poyo.ai

Python

python python/generate.py
python python/generate.py payloads/heygen-avatar-6-turbo-avatar-text.json

python/generate.py uses only the Python standard library.

Node.js

node node/index.mjs
node node/index.mjs payloads/heygen-avatar-6-reference-video.json

cURL

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

Example requests

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.

Input modes: photo, character video, or public avatar

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.

Writing HeyGen Avatar 6 prompts

  • 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: prompt takes up to 1,200 characters about gestures, expression, and posture; the speech comes from audio_url or text.
  • 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-turbo at 1080p, then switch the model ID to heygen-avatar-6 and set resolution to 2K for the final cut.

More request examples are in the API reference.

Request fields

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 Avatar 6 API pricing

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.

Cost per clip

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.

Async production flow

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.

Common errors

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.

HeyGen Avatar 6 API FAQ

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.

Repository map

Related repositories

Links

License

MIT

About

HeyGen Avatar 6 API examples in cURL, Python, and Node.js: a talking avatar API for heygen-avatar-6 and heygen-avatar-6-turbo. Turn a photo, an animated character video, or a HeyGen public avatar into a lip-synced 1080p or 2K video.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages