how-tos

HeyGen Avatar 6 API Text to Avatar: Presenter Videos from a Script, No Audio File

Poyo.ai Team
9 min read
Share:

HeyGen Avatar 6 API text to avatar: a presenter video from a script

The HeyGen Avatar 6 API can make a presenter video from nothing but a script. In public avatar mode you name one of HeyGen's 1,248 stock looks, send up to 1,000 characters of text, pick one of 102 voices, and heygen-avatar-6 (or heygen-avatar-6-turbo) returns a lip-synced MP4. No photo, no recording, no text-to-speech step on your side. This walkthrough covers choosing a look and a voice from the catalog, directing gestures with prompt, choosing a frame shape, and what a text request costs. You can browse the looks on the HeyGen Avatar 6 model page as well.

The text-to-avatar request

This is the documented body for public avatar mode 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"
  }
}
FieldRequiredRule
avatarYesOne of 1,248 look names
textYes (instead of audio_url)1–1,000 characters
voiceNoOne of 102 names; default Warm Pro Narrator
promptNoUp to 1,200 characters of direction
aspect_ratioNo16:9 (default), 9:16, 1:1, 4:5, 5:4
resolutionNo1080p (default) or 2K

The presence of avatar is what selects this mode. Do not also send image_urls or video_url; use one mode's inputs per request. Submit to POST https://api.poyo.ai/api/generate/submit and poll /api/generate/status/{task_id} as in the HeyGen Avatar 6 API guide.

Pick an avatar look from the catalog

PoYo publishes every name on the Avatars and Voices page and as a JSON catalog. The catalog has five keys:

KeyContents
modelsheygen-avatar-6, heygen-avatar-6-turbo (the same names work on both)
default_voiceWarm Pro Narrator
avatarsAll 1,248 look names, flat
avatars_by_personThe same looks grouped under 156 people
voicesAll 102 voice names

Each person has one or more looks, and each look is a separate avatar value. Abigail has five (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); Annie has 54; eight people have a single look. The names describe setting, outfit, and camera angle, which is usually enough to choose without previewing:

You wantLook for names likeExamples
Presenter facing cameraFrontAbigail Office Front, Bryan Suit Front
Three-quarter angleSideAbigail Office Side
Seated, informalSofa, Sitting, LoungeAnnie Sofa Sitting Front
A role or settingDoctor, Nurse, Yoga, Tech ExpertAnn Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert

About 480 names contain Front and about 430 contain Side. For an explainer series, pick one person and keep to their Front looks, so the presenter stays the same across videos. Use the matching Side look for cutaways.

Names match regardless of letter case and extra spaces, so abigail office front selects Abigail Office Front. PoYo checks avatar against the list at submission, so a typo returns an immediate 400 rather than a failed task. Validate in your own code first:

import requests

catalog = requests.get(
    "https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()

def norm(name: str) -> str:
    return " ".join(name.split()).lower()

AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])

def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
    if norm(avatar) not in AVATARS:
        raise ValueError(f"unknown avatar: {avatar!r}")
    if not 1 <= len(text) <= 1000:
        raise ValueError("text must be 1-1,000 characters")
    if voice is not None and voice not in VOICES:
        raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
    if prompt is not None and len(prompt) > 1200:
        raise ValueError("prompt must be at most 1,200 characters")
    body = {"avatar": AVATARS[norm(avatar)], "text": text,
            "aspect_ratio": aspect_ratio, "resolution": resolution}
    if voice:
        body["voice"] = voice
    if prompt:
        body["prompt"] = prompt
    return {"model": model, "input": body}

The voice check uses exact names on purpose; the next section explains why.

Pick a voice

voice decides who reads text. Leave it out and you get Warm Pro Narrator. The 102 voices include plain names (Andrew, Ivy, Jessica Anne Bogart), descriptive ones (Calm Chloe, Professor Dean, Radio Rick, Chill Brian), and some with a style tag in the name.

Three things trip people up:

  • Trailing spaces can matter. The docs call out that Hope and Hope (with a trailing space) are two different voices. Archer , Cassidy , Adam Stone , Spuds Oxley , and Andrew Rizz also end with a space in the catalog. Copy names from the JSON rather than retyping them.
  • Some names contain emoji or file-like suffixes, such as Cute Chloe - Friendly 😊 or Brenda - UGC - 1.mp4. Those characters are part of the name. Send the request body as UTF-8 JSON and the name will pass through unchanged.
  • The voice is not tied to the avatar. Any of the 102 voices can read for any of the 1,248 looks. Pick a voice that suits the person on screen; our launch-day tests paired Bryan Tech Expert with Andrew and Abigail Office Front with Jessica Anne Bogart.

voice applies only when you send text. If you send audio_url instead, the avatar speaks your recording and voice is not used.

Direct gestures with prompt

prompt takes up to 1,200 characters of direction for gestures, expression, and posture. HeyGen's technical report describes the technique: "Write the action next to the words. Avatar 6 performs it right on cue." Its example: "Friendly pharmacist. On 'Hello', give a thumbs up. On 'the counter on the left', point to the side with your index finger."

A pattern that follows that format:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Bryan Tech Expert",
    "text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
    "voice": "Andrew",
    "prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}

Tips that keep prompts useful:

  • Quote the exact words from text that each action should land on, so the cue is unambiguous.
  • Describe one role or mood first ("Friendly product expert"), then the cues.
  • Leave prompt out when you have no specific cues. HeyGen's Avatar 6 launch page says the model "matches gesture, emotion, and expression to your script" on its own.

Choose the aspect ratio for the placement

aspect_ratio exists only in public avatar mode; photo and reference video modes keep the input's shape.

Placementaspect_ratio
Website, YouTube, LMS lesson16:9 (default)
Shorts, Reels, TikTok, stories9:16
Square feed post, in-app card1:1
Portrait feed post4:5
Landscape feed post5:4

resolution is separate: 1080p or 2K in any ratio. 2K costs more per second, so render drafts at 1080p.

How long the video will be, and what it costs

With text, the video runs as long as the avatar takes to read it, up to 1,000 characters. You are billed for the finished video's length, rounded up to whole seconds. Credits are reserved when you submit and settled to the actual seconds when the task finishes.

Our launch-day tests on the production API, November 19, 2026 (16:9, 1080p):

ModelAvatar / voiceScriptOutputCost at current pricesWall time
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27 words10.16 s110 credits ($0.55)About 2.4 min
heygen-avatar-6Bryan Tech Expert / Andrew21 words6.88 s140 credits ($0.70)About 2 min

That works out to roughly 2.7 and 3.1 words per second in these two runs, useful for a rough budget but not a guarantee, since pacing varies by voice and script. Rates per second: Turbo 10 credits ($0.05) at 1080p or 18 ($0.09) at 2K; Avatar 6 20 credits ($0.10) or 29 ($0.145). See HeyGen Avatar 6 API pricing for more.

Because text tasks hold a reservation while they run, firing many at once can return HTTP 200 with body code 402 (insufficient_credits_error). In our test, a third request was refused with: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Queue text jobs, or keep a balance that covers the reservations in flight. Use Turbo while you iterate; the Avatar 6 vs Turbo comparison shows when to switch.

Frequently asked questions

Can the HeyGen Avatar 6 API turn text into a talking avatar video?

Yes. In public avatar mode, send avatar, up to 1,000 characters of text, and optionally voice. No audio file is needed.

Where is the list of HeyGen Avatar 6 API avatars and voices?

On the PoYo docs page Avatars and Voices, and as a downloadable JSON catalog with avatars, avatars_by_person, and voices keys.

What is the default voice in the HeyGen Avatar 6 API?

Warm Pro Narrator, used when voice is omitted.

Can I use my own photo with text instead of a stock avatar?

No. text works only in public avatar mode. For your own photo, use photo mode with image_urls and an audio_url; generate the audio with a TTS model first if needed.

What aspect ratios does HeyGen Avatar 6 text to avatar support?

16:9, 9:16, 1:1, 4:5, and 5:4, at 1080p or 2K.

How is a HeyGen Avatar 6 API text request billed?

By the finished video's length, rounded up to whole seconds, at the model's per-second rate. Credits are reserved at submission and settled when the task ends.

Share: