Discover HeyGen’s six core APIs and find out when to use Video Generation, Video Agent, Template, Translation, Proofread and Text to Speech to scale your AI video workflows.
The HeyGen API is a suite of REST endpoints for generating, translating and voicing AI video without cameras, studios or editing teams. It is organised into six core APIs: Video Generation, Video Agent, Template, Video Translation, Proofread and Text to Speech. This guide explains what each API does, which endpoint it calls, which parameters matter and the tasks it is designed for, so you can choose the right one for your needs.
If you are evaluating HeyGen for programmatic video, here is a brief overview: use Video Generation or Video Agent to create a video; the Template API to produce variations at scale; Video Translation and Proofread to localise it; and Text to Speech when you only need the audio.
An overview of the 6 HeyGen APIs
Video Generation
What it does: Creates an avatar-led video from a script or audio file
Endpoint: POST /v3/videos
Best for: Onboarding, L&D, product guides
Video Agent
What it does: Creates a finished video from a text prompt, from start to finish
Endpoint: POST /v3/video-agents
Best for: Turning wikis or knowledge bases into videos, quick drafts
Template
What it does: Creates video variations that follow your brand guidelines from a reusable template
Endpoint: POST /v2/template/{template_id}/generate
Best for: Personalised video at scale
Video Translation
What it does: Translates and dubs a video into over 175 languages with lip-sync
Endpoint: POST /v3/video-translations
Best for: Localising launches and training
Proofread
What it does: Extracts an editable transcript to review before translating
Endpoint: POST /v3/video-translations/proofreads
Best for: Accuracy checks before localisation
Text to Speech
What it does: Synthesises natural speech audio from text
Endpoint: POST /v3/voices/speech
Best for: Voiceovers, narration, audio tracks
All six follow the same authentication and async conventions, described in the common conventions section below.
What does the HeyGen Video Generation API do?
The HeyGen Video Generation API creates an avatar-led video from a text script or a pre-recorded audio file, with no camera or studio required. It provides the core functionality for creating videos in which a single avatar delivers a message, and is designed to automate the production of onboarding and L&D videos.
What it does:
- The API animates a HeyGen avatar, including studio avatars, digital twins, and a talking photo AI, using either a text script paired with a voice_id or an uploaded audio track for lip-syncing. Script and audio cannot be used together.
- Supports the Avatar IV and Avatar V engines. Avatar IV is the default, and you set the
enginefield to select Avatar V for eligible avatars. Avatar III generation uses the legacy v1 or v2 API. - Outputs at 4k, 1080p or 720p, with aspect ratios including 16:9, 9:16, 4:5, 1:1 and auto, as either an MP4 or a WebM with a transparent background.
- Adds backgrounds and background removal, burnt-in or sidecar captions, and a custom watermark for selected Enterprise customers.
- For photo avatars on Avatar IV, it accepts a
motion_promptand anexpressivenesslevel to control body motion.
When to use it: You have a script or audio track and want a single avatar to deliver it programmatically, at scale, for onboarding, training or product walkthroughs.
Endpoint: POST /v3/videos
What does the HeyGen Video Agent API do?
The HeyGen Video Agent API turns a single text prompt into a finished video, handling scripting, avatar selection, scene composition and automatic rendering. It offers a quick route from an idea or document to a first draft ready to watch.
What it does:
- Runs in two modes.
generateruns once without further input, automatically working through the storyboard to produce a video. Meanwhile,chatsupports an ongoing conversation, pausing for key decisions such as choosing a voice, and allowing revisions and follow-up videos. - Accepts up to 20 file attachments, so you can base a video on an internal wiki, a product document or a knowledge base article.
- Takes optional
avatar_id,voice_id,style_id, andbrand_kit_idto apply specific avatars, voices, curated visual styles, and brand colours, fonts, and logos. - Automatically detects orientation from the content when
orientationis not provided.
When to use it: You need a video based on a prompt or internal documentation, a quick first draft, or a way for non-technical colleagues to create a video from a brief.
Endpoint: POST /v3/video-agents
How does the HeyGen Template API work?
The HeyGen Template API creates variations of a video from a reusable template by replacing placeholder variables. You set the avatar, voice, layout and branding once, then produce multiple on-brand versions of a corporate brand video at scale.
What it does:
- Replaces template placeholders using a
variablesmap. Each variable has a type — text, image, video, audio, voice or character — and carries a type-specificpropertiespayload, such as replacement copy, a media URL or asset ID, avoice_idor a character_id for an avatar or talking photo. - Restricts a render to a subset of scenes with
scene_ids, overrides outputdimensionandfps, and adds burnt-in subtitles. - Applies a brand glossary for translation and pronunciation rules, organises output into a folder, and can render in
testmode at lower quality without deducting quota.
When to use it: You need personalised video at scale, such as account-based sales videos or localised versions of a single layout, while maintaining brand consistency across every render.
Endpoint: POST /v2/template/{template_id}/generate. Note that this is a v2 endpoint.
What does the HeyGen Video Translation API do?
The HeyGen Video Translation API translates and dubs an existing video into one or more target languages, with voice cloning and lip-sync. It localises training and product launches in over 175 languages and dialects with 99% lip-sync accuracy.
What it does:
- Returns one
video_translation_idper language. Pass a single language for one translation, or several for a batch. - Offers two quality modes.
speedis the default for a quick turnaround.precisionproduces higher-quality lip-sync using avatar inference. - Includes controls for
translate_audio_only, captions, speaker separation viaspeaker_num, partial translation withstart_timeandend_time, background music removal and speech enhancement. - Applies a brand glossary to ensure specialist terms are translated correctly, for example, recognising "Reformer" as Pilates equipment rather than a political activist.
When to use it: You have a finished source video and need accurate, lip-synced versions for other markets to support launches, training or product education.
Endpoint: POST /v3/video-translations
How does the HeyGen Proofread API work?
The HeyGen Proofread API extracts editable subtitles from a video, allowing you to review and correct the transcript before final translation and rendering. It provides a quality assurance check before Video Translation.
What it does:
- Creates a proofreading session with the source transcript displayed as editable subtitles, so you can correct names, jargon, brand terms or transcription errors before any translations are produced.
- Includes the same localisation controls as the Translation API, including a brand glossary,
speaker_num, thespeedandprecisionmodes, music removal and speech enhancement. - Accepts one or more
output_languages, so you can prepare a single proofread or batch several at once.
When to use it: Transcript accuracy matters before you localise, for example, with technical terminology, regulated content, or brand names that must not be mistranslated.
Endpoint: POST /v3/video-translations/proofreads
How does the HeyGen Text to Speech API work?
The HeyGen Text to Speech API synthesises speech from text using a chosen voice. It is a standalone voice engine for narration and audio tracks, offering consistent output, low latency and control over emotional expression.
What it does:
- Uses voices that support the starfish engine. Find compatible voices with
GET /v3/voices?engine=starfish. - Accepts plain text or SSML markup, synthesises up to 5,000 characters per request, and supports a speed multiplier from 0.5 to 2.0x.
- Automatically detects the language from the text, or lets you set it explicitly with a
languageor a BCP-47localetag. - Returns a URL for the generated audio file, along with its duration and optional word-level timestamps.
When to use it: You need a standalone voiceover or narration track, or audio to pass to the Video Generation API for lip-sync. Word-level timestamps are useful for captioning and precise synchronisation.
Endpoint: POST /v3/voices/speech
Which HeyGen API is right for you?
Match the task to the API:
- I’d like a video of an avatar reading my script. Use the Video Generation API.
- I want a video from just a prompt or a wiki article. Use the Video Agent API.
- I need multiple on-brand versions of the same video. Use the Template API.
- I have a finished video and need it in other languages. Use the Video Translation API.
- I want to correct the transcript before translating. Use the Proofread API.
- I only need an audio voiceover. Use the Text to Speech API.
Using the HeyGen APIs together
The six APIs are designed to work together in pipelines:
- Prompt to localised video: Draft with the Video Agent API or script with the Video Generation API, run the Proofread API to check the transcript, then dub into the target languages with the Video Translation API.
- Audio-first production: Generate a track with the Text to Speech API, then lip-sync an avatar to it through the Video Generation API using
audio_urloraudio_asset_id. - Personalisation at scale: Build a layout once and render hundreds of variants with the Template API, optionally supplying voices from Text to Speech.
They also share building blocks. Brand glossary IDs are reused across Translation, Proofread, and Template to keep terminology consistent, and async completion is reported through callback_url webhooks on the endpoints that support them.
Shared conventions in the HeyGen API
- Authentication: Every endpoint requires your HeyGen API key in the
x-api-keyheader. Obtain it from your HeyGen dashboard. - Safe retries: Mutation endpoints accept an optional
Idempotency-Keyheader. A retry within 24 hours that reuses the key replays the original response, so you can retry safely without creating duplicate jobs. - Asynchronous results: Video jobs take time to process. Provide a
callback_url, and optionally acallback_id, to receive a webhook when rendering is complete rather than polling.
Getting started
Choose the API that suits your task from the table above, authenticate using your x-api-key header, and provide a callback_url to receive results once rendering is complete. Full request and response schemas for each endpoint are available in the HeyGen API documentation.
Common questions
What is the HeyGen API?
The HeyGen API is a set of REST endpoints for creating, translating and adding voiceovers to AI video programmatically, without cameras or studios. It includes six core APIs covering video generation, prompt-to-video, template-based video, translation, transcript proofreading and text to speech.
How many APIs does HeyGen have, and what are they?
HeyGen offer six core video APIs: Video Generation, Video Agent, Template, Video Translation, Proofread and Text to Speech.
Which HeyGen API can translate videos?
The HeyGen Video Translation API translates and dubs video into other languages using voice cloning and lip-sync, via POST /v3/video-translations.
How do the Video Generation API and Video Agent API differ?
The Video Generation API renders an avatar speaking a script or audio you provide, giving you direct control over the avatar, voice and output. The Video Agent API takes a single prompt and handles scripting, avatar selection, scene composition and rendering for you. This is faster, but gives you less manual control.
Do HeyGen offer a text-to-speech API?
Yes. The HeyGen Text to Speech API synthesises speech from text using starfish-engine voices, supports plain text or SSML and a speed range of 0.5 to 2.0x, and returns an audio URL with the duration and optional word-level timestamps via POST /v3/voices/speech.
How many languages are supported by HeyGen Video Translation?
The HeyGen Video Translation API supports over 175 languages and dialects with 99% lip-sync accuracy.
What can you do with the HeyGen Proofread API?
The HeyGen Proofread API extracts an editable transcript from a video, enabling you to correct names, jargon and errors before translation. This improves the accuracy of the final localised videos.
Can I create personalised videos at scale with HeyGen?
Yes. The HeyGen Template API lets you define the avatar, voice, layout and branding once, then render multiple variations by passing values into typed template variables, at POST /v2/template/{template_id}/generate.
How do I authenticate with the HeyGen API?
Send your HeyGen API key in the x-api-key request header. You can find your key in your HeyGen dashboard.








