background leftbackground right

A guide to the six core HeyGen APIs and when to use them

Tony Faccenda
Written byTony Faccenda
Last UpdatedNovember 18th, 2026
HeyGen API guide featuring a cURL request example for the photo avatar API.
Create AI videos, starring you in 177+ languages and dialects.
Get started for free
Summary

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 engine field 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_prompt and an expressiveness level 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. generate runs once without further input, automatically working through the storyboard to produce a video. Meanwhile, chat supports 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, and brand_kit_id to apply specific avatars, voices, curated visual styles, and brand colours, fonts, and logos.
  • Automatically detects orientation from the content when orientation is 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 variables map. Each variable has a type — text, image, video, audio, voice or character — and carries a type-specific properties payload, such as replacement copy, a media URL or asset ID, a voice_id or a character_id for an avatar or talking photo.
  • Restricts a render to a subset of scenes with scene_ids, overrides output dimension and fps, and adds burnt-in subtitles.
  • Applies a brand glossary for translation and pronunciation rules, organises output into a folder, and can render in test mode 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_id per language. Pass a single language for one translation, or several for a batch.
  • Offers two quality modes. speed is the default for a quick turnaround. precision produces higher-quality lip-sync using avatar inference.
  • Includes controls for translate_audio_only, captions, speaker separation via speaker_num, partial translation with start_time and end_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, the speed and precision modes, 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 language or a BCP-47 locale tag.
  • 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_url or audio_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-key header. Obtain it from your HeyGen dashboard.
  • Safe retries: Mutation endpoints accept an optional Idempotency-Key header. 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 a callback_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.

Read the 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.

Continue Reading

Latest blog posts related to A guide to the six core HeyGen APIs and when to use them.

Browse All

Start creating videos with AI

See how businesses like yours scale content creation and drive growth with the most innovative AI video.