A HeyGen avatar video is a script, a voice, and a look that mouths the words. You can build that in AI Studio for a course intro, or send the same three pieces to POST /v3/videos. Translation dubs speech. It does not rewrite words painted into the frame. This lab uses the help center and the v3 docs as they read in October 2026.

Write the script in AI Studio

The AI Studio script article says each scene has its own script. Add Scene, then choose Blank or From Template, and type in the script editor. Assign an avatar, a voice, and a background after the words exist. The script is what the avatar says. It is not a caption track unless you add captions separately.

The same article says you can download or upload the full script from the top-left menu, including pause positions. The file is read in the browser and is not uploaded as the script file itself. Limits stated there:

  • A line, paragraph, or cell over 1,000 characters is split into more than one segment.
  • One segment maps to one scene, in order. Extra segments create extra scenes.
  • Empty lines and empty cells are skipped.
  • If the video already has text, the upload adds scenes. It does not replace what is there.
  • If you select several files, only the first is used.
  • .doc is not accepted. Save Word files as .docx.
  • For .txt, put each scene on its own line. For Excel or CSV, put each scene in its own cell.

For a course intro, write one sentence per scene. Scene one is the promise (“this lesson fixes ImagePullBackOff”). Scene two is the command the viewer will run. Scene three is where the written steps live on your site. Short scenes are easier to replace when a flag changes.

Pronunciation of product names is a glossary problem, not a spelling problem. The script article points at fixing pronunciation in the editor. The Brand Glossary section below is the durable version of that fix.

Avatars and voices

In the product, a Brand System has an Avatars tab. Add Brand Avatar picks the looks that belong to that brand, so a lesson series does not drift across stock faces.

On the API, avatar_id can be a video avatar or a photo-avatar look. The create-video reference says the types are studio avatar, digital twin, and photo avatar. If you omit engine, the server uses Avatar IV. Set engine.type to avatar_v only when you mean Avatar V. The enterprise pricing page says Avatar V is for digital twins. Do not send Avatar V for a look the reference says is rejected. Photo avatars can take a motion_prompt on either engine. Video avatars take motion_prompt when the engine is Avatar V. The reference says Avatar IV rejects that prompt for video avatars.

expressiveness (high, medium, low) is photo avatars on Avatar IV only. It defaults to low when omitted, and it is rejected for Avatar V.

Voices are ids, not display names. GET /v3/voices lists them. The usage-limits page says that list defaults to 20 and caps a page at 100. GET /v3/avatars defaults to 20 and caps at 50. Both use a limit and a next_token.

The quick start also names two clone paths in the product: an instant voice from one recording, and a professional clone trained on 20 or more minutes of audio. Pass the resulting voice_id into the video call. Optional voice_settings on create include speed, pitch, volume, and locale.

You can skip synthesis and pass audio_url or audio_asset_id instead of script. Those two are mutually exclusive with letting the script drive the voice. A URL you pass must be public. The quick start’s troubleshooting note says a 400 download_failed means the URL could not be fetched.

Brand System and glossary

The help article calls this a Brand System, not a loose pile of uploads. Tabs:

  • Brand Spec: colors (including a hex value) and fonts for Body, Caption, Display, Heading, and Heading 2.
  • Assets: images and videos, via Upload Brand Assets.
  • Logos: Upload Brand Logos.
  • Motion: motion pieces saved from Video Agent.
  • Avatars: Add Brand Avatar.

Upload limits on that article, as of the page read in October 2026: resolution up to 4096 by 4096. JPG or PNG images and logos up to 200 MB (it also states 4167 by 4167). MP4 or MOV up to 200 MB. TTF or OTF fonts up to 100 MB.

You apply a Brand System from AI Studio with Brand on the right menu, or from Video Agent by the + control beside the prompt, then Brand System.

Brand Glossary is the second half of branding. Open Brand in the left navigation, then Brand Glossary.

  • Pronunciation rules affect AI Studio text-to-speech. The article says those words show in italicized purple in the script editor.
  • Translation rules are Force Translate (use this wording) or Don’t Translate (leave the term). They apply when a Video Translation job uses the glossary.

On the API, brand_glossary_id changes how script is spoken. The reference says a supplied audio_url or audio_asset_id is not rewritten by the glossary. Captions still show the original script words. Pronunciation is the audio only. Discover ids with GET /v3/brand-glossaries.

folder_id is not a brand kit. The reference says a brand-kit project id is rejected with 404 before anything is created. Omit folder_id, or pass a real folder id from POST /v3/folders.

Translation and dubbing

Video Translation, in the help article, re-voices the spoken track in another language, using the original speaker’s voice, and can sync lips. You upload a video, pick target languages and a translation engine, and run Translate.

What moves:

  • Spoken audio, in the original speaker’s voice.
  • Lip movement, if you turn that on.
  • On-screen captions, if you turn those on.

What stays:

  • Text that is part of the image: titles, lower-thirds, hard-coded captions.
  • Background music, unless you enable Remove Background Sound.

Singing and music-first videos are called out as inconsistent. Unsupported source languages fail immediately and, the article says, do not use credits. If you need the words on screen in the new language, build that video in the studio. Do not expect translation to repaint pixels.

The API list endpoint GET /v3/video-translations is on the usage-limits page (default page size 10, max 100). This lab does not show a translation POST body, because that request schema was not on the pages read here. The help article does say the API can run translation. Look up the current create call in the developer docs before you automate it.

API usage is billed separately from the app plans. The API pricing help article says API credits are pay as you go and are not the same wallet as a Creator, Pro, or Business subscription. This lab does not copy per-second rates. The self-serve page and the enterprise page use different units.

Generate a video from the API

Base URL https://api.heygen.com. Create a key in the API keys page and export it yourself. The quick start checks the key with GET /v3/users/me. A 401 means the header is missing or the key is inactive.

export HEYGEN_API_KEY="your-key"

List a look and a voice, then create. The quick start writes the header as X-Api-Key. The REST reference writes x-api-key. HTTP header names are case-insensitive. Use one of them, not a query-string key.

curl "https://api.heygen.com/v3/avatars?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl "https://api.heygen.com/v3/voices?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c0b2e-7a11-4d5e-9c31-2b6a8e0d11ab" \
  -d "{\"type\":\"avatar\",\"avatar_id\":\"YOUR_AVATAR_ID\",\"voice_id\":\"YOUR_VOICE_ID\",\"script\":\"This lesson shows how to read a CrashLoopBackOff event before you change the image.\",\"title\":\"CrashLoop lesson intro\",\"aspect_ratio\":\"16:9\"}"

The response body includes video_id and status. The schema’s example status is waiting. An Idempotency-Key of 1 to 255 characters from letters, digits, and _:.- makes a retry within the documented window return the original response instead of a second render. A duplicate still in flight returns 409.

Poll until the job finishes:

curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

The quick start treats completed and failed as the terminal statuses for GET /v3/videos/{video_id}, and it reads video_url from that payload. On failure, read failure_code and failure_message. A 429 means you hit a rate or concurrency limit. Honor Retry-After and back off. You can also pass callback_url on create and skip the poll loop.

Output constraints from the usage-limits page: avatar video is 25 frames per second. Width and height must each sit between 128 and 4096 pixels. Default output is 1080p. The create reference’s aspect_ratio values include 16:9 (the default), 9:16, 4:5, 5:4, 1:1, and auto. A scene longer than 30 minutes fails during render. An avatar request is one scene, so 30 minutes is the whole video. Multi-scene studio and template videos can run longer, as long as each scene stays under that cap. The page also caps scenes at 50. 4k on the create reference is for Avatar III digital twins and studio avatars, not a universal switch.

output_format defaults to mp4. Optional caption can request an srt file. Optional background takes a color value, a URL, or an asset id.

Two other create paths exist, and they are not the script-to-avatar call:

  • POST /v3/video-agents takes a prompt. The quick start polls the session for a video_id, then polls the video. That is Video Agent: the service drafts the piece.
  • POST /v3/models/videos with model heygen-video-1 generates a scene from a prompt (text, image, or reference). The model page says that is a different tool from the avatar engines behind POST /v3/videos.

Use /v3/videos when you already wrote the words. The quick start says v1 and v2 remain supported until October 31, 2026. New code should be v3.

A workflow tool can POST this payload and poll. The pattern for a webhook-triggered HTTP call is in n8n first workflow. An agent that decides when to render is a different design. See what is agentic AI.

Course intros and short tutorials

Use an avatar intro when the lesson is a talking head plus a later screen recording you edit in yourself. HeyGen is a poor place to demonstrate a live terminal. Record the terminal separately, and let the avatar handle the 20 to 40 seconds of framing.

Keep kubectl, image names, and flag spellings in the Brand Glossary so the voice does not invent a pronunciation. Put the typed command on screen in the editor if students must read it. Translation will not convert that overlay.

For a series, lock one avatar, one voice, one Brand System, and 16:9. Switch to 9:16 only for a cutdown, as a second render, not by cropping the lesson in an external tool and hoping the mouth still matches.

Research for the script can start in Perplexity. The spoken draft still has to match a doc you opened. A Gemini pass over the outline is optional. The Gemini tools cheat sheet is the API side of that, not a video renderer.

Quality checklist

  • Read the script aloud. One idea per scene. Split anything the importer would break at 1,000 characters.
  • Confirm avatar_id and voice_id from the list endpoints, not from a screenshot.
  • Set aspect_ratio to the player you ship (16:9 for a course page).
  • Add glossary rules for product names and CLI tools before you render a batch.
  • Do not bake the lesson title into the pixels if you will translate. Add captions as captions.
  • Wait for completed. A waiting or in-progress body has no final file.
  • Play the mp4 with sound. Check the first five seconds of mouth movement and any word you added to the glossary.
  • On failed, copy failure_code and failure_message before you retry. Change the idempotency key only when you intend a new video.
  • On 401, fix the key. On 429, wait for Retry-After. On 400 download_failed, the audio or background URL is not publicly fetchable.
  • Keep the key out of the repo. The quick start’s agent instructions say to export it locally and not paste it into a chat.

FAQ

Which HeyGen API endpoint creates an avatar video from a script?

POST https://api.heygen.com/v3/videos with JSON type avatar, plus avatar_id, script, and voice_id. The header is X-Api-Key. The create call returns video_id and a status such as waiting. Poll GET /v3/videos/{video_id} until the status is completed or failed. v1 and v2 stay supported through October 31, 2026, according to the quick start read in October 2026.

Does HeyGen video translation rewrite on-screen text?

No. The video-translation help article says spoken audio is re-voiced, and lip movement and on-screen captions are optional. Text baked into the picture, graphics, and hard-coded captions stay as they are. Background music stays unless you enable Remove Background Sound. Sung lyrics are not a reliable case.

What is a HeyGen Brand System?

It is the current help-center name for the brand kit: colors, fonts, logos, images, motion elements, and chosen avatars. Brand Glossary is separate. It holds pronunciation rules for AI Studio speech and translation rules (Force Translate or Don’t Translate) used when you run Video Translation with the glossary selected.

Why did POST /v3/videos return 404 for my folder?

The create-video reference says folder_id must be a folder the caller can write, not in the trash. An id from another workspace, or a project of another kind such as a brand kit, is rejected with 404 before a video is created. List avatars with GET /v3/avatars and voices with GET /v3/voices instead of pasting a brand-kit id into folder_id.

How this guide was verified

Written by hand from the official documentation, every command re-checked, and reviewed a second time before publishing. Last reviewed on .

Official sources read for this article

Share.

Haythem Rehouma builds and teaches DevOps and AI tooling: Kubernetes, Docker, Terraform, Claude Code, ChatGPT and n8n. Every KubPoint guide is written from the official docs and re-tested before it goes live.

Comments are closed.