# HeyGen Documentation ## About HeyGen HeyGen is an AI video creation platform — avatars, voice cloning, lip-sync translation, and agentic video workflows. The product is used by 85,000+ companies for marketing, L&D, sales, and global communications. This file indexes the *developer* surface; for the consumer/marketing surface (use cases, pricing, blog), see: - [HeyGen — product site](https://www.heygen.com): Homepage, product overview, pricing, blog. - [www.heygen.com/llms.txt](https://www.heygen.com/llms.txt): Machine-readable index of the marketing site, including links to MCP, API pricing, and use-case pages. ## Start here if you are an AI agent If you are an AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, etc.) acting on a user's behalf, read [For AI Agents](https://developers.heygen.com/docs/for-ai-agents.md) **before** the API reference. It defines the auth-detection ladder you must follow and the failure mode to avoid (writing curl scripts that can't run because auth was never verified). Priority order — **API key first**: 1. **CLI with an API key** — if `heygen` is on PATH and `heygen auth status` returns an API-key account (or `HEYGEN_API_KEY` is set), drive the workflow via [`heygen` commands](https://developers.heygen.com/commands.md). Best default for scripting, batches, and repeatable pipelines. 2. **HeyGen API with an API key** — direct HTTPS calls to `api.heygen.com` with the `X-Api-Key` header. Require `HEYGEN_API_KEY` in the environment, then follow the [Quick Start](https://developers.heygen.com/docs/quick-start.md). Never ask the user to paste an API key into chat. 3. **OAuth (MCP or `heygen auth login --oauth`)** — trial-scale only. If the user is new and wants to test a one-off feature, OAuth is the fastest path to a few small generations: `mcp__heygen__*` tools ([MCP Overview](https://developers.heygen.com/mcp/overview.md)) or CLI OAuth, both billed against the user's HeyGen subscription credits. For anything at scale — batches, pipelines, production traffic — switch to an [API key](https://developers.heygen.com/docs/api-key.md): higher limits, API billing, and key rotation. Recommended: install the official agent skills from [`heygen-com/skills`](https://github.com/heygen-com/skills) — see [`INSTALL_FOR_AGENTS.md`](https://github.com/heygen-com/skills/blob/master/INSTALL_FOR_AGENTS.md) and the [Skills docs](https://developers.heygen.com/skills/overview.md). ## Getting Started - [For AI Agents](https://developers.heygen.com/docs/for-ai-agents.md): Agent-first onboarding — auth detection, skills install path, and rules for agents generating HeyGen videos on a user's behalf. - [Quick Start](https://developers.heygen.com/docs/quick-start.md): Get from zero to a generated video in minutes — auth, create, poll. - [Stripe Projects](https://developers.heygen.com/docs/stripe-projects.md): Fund API usage with a Stripe-backed project wallet — for agents provisioning on a user's behalf. - [Discord](https://developers.heygen.com/docs/discord.md): Join the HeyGen developer community on Discord for direct access to engineers, PMs, and other developers. - [Slack Integration](https://developers.heygen.com/docs/slack.md): Generate HeyGen videos from Slack — connect, prompt, and share. - [Changelog](https://developers.heygen.com/changelog.md): Product updates and announcements for the HeyGen API and developer platform. ## Authentication **Two auth models.** An **API key** ([generate and secure one here](https://developers.heygen.com/docs/api-key.md)) authenticates the CLI and raw API, bills to API plans, and is the right choice for production, batches, and anything repeatable. **OAuth** (MCP and CLI `--oauth`) authenticates as the user's web account and draws on subscription credits — convenient for a new user's first few small test generations, sized for trial rather than scale. - [API Key](https://developers.heygen.com/docs/api-key.md): Generate, rotate, and secure your HeyGen API key. Verify it with `GET /v3/users/me`. - [API Key Permission Scopes](https://developers.heygen.com/docs/api-key-permissions.md): Map restricted API key read and write scopes to the public endpoints that require them. ## Account & Billing - [Get Current User](https://developers.heygen.com/user-profile.md): Retrieve the authenticated user's profile, credit balance, and plan tier — useful for in-app credit displays and account UIs. - [Self-Serve Pricing](https://platform.heygen.com/pricing): Per-operation pricing for self-serve API plans, shown in the API dashboard. - [Enterprise Pricing](https://www.heygen.com/contact-us/sales): Enterprise contract pricing is not published — your account team walks you through the billing models. - [Usage Limits](https://developers.heygen.com/docs/usage-limits.md): Rate limits, concurrency, and quota behavior across HeyGen API endpoints. - [Burst Concurrency](https://developers.heygen.com/docs/burst.md): Enterprise workspaces run above their included concurrency on demand; extra cap up to +50, 1.5× the contract rate only on workflows that burst. ## Errors & Versioning - [Error Codes](https://developers.heygen.com/docs/error-codes.md): Error codes, HTTP status codes, and troubleshooting for the HeyGen API. - [Endpoint Version Comparison](https://developers.heygen.com/endpoint-version-comparison.md): v1/v2 vs v3 endpoint coverage and migration guidance. ## Video Agent - [Prompting Guide](https://developers.heygen.com/docs/prompting-guide.md): Write Video Agent prompts that land on the first cut — duration, style paragraphs, and scene-by-scene scripts. - [Prompt to Video](https://developers.heygen.com/docs/video-agent.md): Create videos from a text prompt with full control over avatar, voice, style, and file inputs. - [Styles & References](https://developers.heygen.com/docs/styles-and-references.md): Browse and apply curated visual styles to Video Agent videos. - [Interactive Sessions](https://developers.heygen.com/docs/interactive-sessions.md): Review storyboards, send follow-up messages, and iterate with the Video Agent before generating. - [Edit Scenes](https://developers.heygen.com/docs/edit-scenes.md): Revise only the scenes you name in a Video Agent video: read GET /v3/videos/{video_id}/scenes for scene ids and edit_version, send an edit_plan, poll the new draft. Untouched scenes keep script and visuals. - [Video Agent Styles (CLI Recipe)](https://developers.heygen.com/video-agent-with-styles.md): Pick a visual style — cinematic, handmade, retro — and let the Video Agent handle the rest. - [Writing Effective Video Prompts](https://developers.heygen.com/writing-effective-video-prompts.md): What actually works when prompting Video Agent — based on real experiments, not theory. ## Direct Video Generation **Recommended request defaults for `POST /v3/videos`:** set `aspect_ratio: "auto"` (matches the source footage or image, falling back to `16:9`) and `resolution: "1080p"`. Both are supported on the `avatar` and `image` video types. Cinematic Avatar (`type: "cinematic_avatar"`) supports `16:9`/`9:16`/`1:1` only — no `auto` — at `720p` or `1080p`. The `studio` type composes multiple whole-frame scenes with global output settings. - [Models](https://developers.heygen.com/models.md): The models behind the API — HeyGen Video for prompt-to-video, the Avatar V, IV, and III rendering engines compared, plus the HeyGen Voice model with its instant and professional clone tiers. - [HeyGen Image](https://developers.heygen.com/docs/models/heygen-image.md): Identity-focused portraits with `heygen-image-1` on POST /v3/models/images: one identity, any scene. Six-scene showcase (input to output), copyable agent prompt, full API (inputs, aspect ratios, polling, errors). - [HeyGen Video](https://developers.heygen.com/docs/models/heygen-video.md): Prompt-to-video model `heygen-video-1` on POST /v3/models/videos: text, image, or reference to video, 5–15 s clips with their own audio. Use POST /v3/videos instead to animate an avatar from a script. - [Avatar V](https://developers.heygen.com/avatar-v.md): Avatar V is HeyGen's highest-fidelity v3 rendering engine, using cross-reference-driven animation for the most natural motion and lip-sync. Opt-in per look. - [Avatar IV](https://developers.heygen.com/avatar-iv.md): Avatar IV is the default HeyGen v3 rendering engine — the broadest avatar support, arbitrary image animation, motion_prompt, and expressiveness control. - [Avatar III](https://developers.heygen.com/avatar-iii.md): Avatar III is HeyGen's v3 rendering engine built around a dedicated photo-to-video pipeline, with a higher-quality re-engineered model for photo avatars and video avatars (digital twins and studio avatars). - [Live Avatar](https://developers.heygen.com/live-avatar.md): Real-time, conversational avatars via the LiveAvatar API. Full docs at docs.liveavatar.com. - [Digital Twin](https://developers.heygen.com/generate-avatar-video.md): A Digital Twin is a lifelike avatar trained from real video footage of a person. Once created, you can make it speak any script in any supported voice — no camera or studio required. - [Photo Avatar](https://developers.heygen.com/photo-avatar.md): A Photo Avatar is created from a single still image of a person. HeyGen animates the face, syncs lip movements to your script, and produces a realistic talking-head video — all from one photo. - [Cinematic Avatar](https://developers.heygen.com/cinematic-avatar.md): Camera-directed avatar videos (`type: "cinematic_avatar"`) — multi-shot prompts, cinematic motion, and scene direction on top of avatar speech. - [Image to Video](https://developers.heygen.com/image-to-video.md): Animate a person in any image directly into a lip-synced talking video — no avatar creation step. Ideal for one-off videos and rapid prototyping. - [Audio to Video](https://developers.heygen.com/audio-to-video.md): Bring your own audio — a voice memo, a podcast segment, a dubbed track — and lip-sync it onto your avatar, digital twin, or any image with one HeyGen API call. - [Photo to Video (CLI Recipe)](https://developers.heygen.com/photo-to-video.md): Turn a single headshot into a talking avatar video — upload, create, voice, render. All from the CLI. - [Transparent Background Videos](https://developers.heygen.com/transparent-background-videos.md): Render avatar videos with a transparent background (WebM) for compositing into your own scenes and players. - [Assets](https://developers.heygen.com/assets.md): Upload files for use across the HeyGen API. - [Upload Assets](https://developers.heygen.com/docs/upload-assets.md): Upload images, video, audio, and PDFs to use as file inputs in Video Agent and other endpoints. - [Folders](https://developers.heygen.com/folders.md): Create workspace folders and place generated videos and translations in them. - [Batch Videos](https://developers.heygen.com/batch-videos.md): Submit up to 100 video creation requests in a single call. Queue avatar, image, cinematic avatar, and studio videos together, then poll one batch id for per-item progress. - [Batch Video Translations](https://developers.heygen.com/batch-video-translations.md): Submit up to 100 video translation requests in a single call. Fan one source video out to many languages, then poll one batch id for per-item progress. - [Batch Lipsyncs](https://developers.heygen.com/batch-lipsyncs.md): Submit up to 100 lipsync requests in a single call. Re-sync many videos to new audio tracks together, then poll one batch id for per-item progress. - [Batch Assets](https://developers.heygen.com/batch-assets.md): Upload up to 100 files in one batch: request presigned S3 slots in a single call, PUT the bytes in parallel, then finalize and poll one batch id. ## Avatars - [Create Avatar](https://developers.heygen.com/docs/create-avatar.md): The four ways to create an avatar (footage, photo, prompt, Look Pack) and which guide to use. Creation returns an avatar_item (the look) and an avatar_group (the character identity); the look ID is what you pass as avatar_id when creating videos. - [Video to Avatar](https://developers.heygen.com/docs/avatar-from-video.md): Train a digital twin from footage of a person with POST /v3/avatars type digital_twin. Covers footage targets (15-600s, one person, audible speech), the voice cloned from the same recording, failure codes, and consent. - [Photo to Avatar](https://developers.heygen.com/docs/avatar-from-photo.md): Create an avatar from one still image with POST /v3/avatars type photo. No consent step; the photo becomes the identity reference for every later look. - [Prompt to Avatar](https://developers.heygen.com/docs/avatar-from-prompt.md): Generate a synthetic character from text with POST /v3/avatars type prompt, or restyle a look you already own by passing it as avatar_id. Includes the avatar_id vs avatar_group_id matrix, reference_images, and aspect_ratio. - [Look Packs and Templates](https://developers.heygen.com/docs/avatar-look-packs.md): Generate a curated set of looks for an avatar you own with POST /v3/avatars/looks. type look_pack applies a Look Pack, type template restyles into a single look template. - [Avatar Consent](https://developers.heygen.com/docs/avatar-consent.md): How HeyGen verifies that the person in a digital twin agreed to be cloned. Covers the three increasing levels of consent access (record via webcam, upload a consent video, skip consent) and the POST /v3/avatars/{group_id}/consent flow. - [Avatar Groups](https://developers.heygen.com/docs/avatars.md): List avatar groups (characters) with cursor-based pagination. Each group contains one or more looks (outfits/styles) — use the Avatar Looks endpoint to browse them. - [Avatar Looks](https://developers.heygen.com/docs/avatar-looks.md): List avatar looks (outfits/styles) with cursor-based pagination and filtering. Each look has a unique ID that you pass as avatar_id to POST /v3/videos or POST /v3/video-agents. ## Voices - [Voices Overview](https://developers.heygen.com/docs/voices/overview.md): Browse available voices, design custom voices with AI, and use them in your videos. - [HeyGen Voice](https://developers.heygen.com/docs/models/heygen-voice.md): HeyGen's in-house voice model — instant voices from one recording (mode instant, new October 2026) and professional clones trained per speaker, completed or streaming speech, professional slot pricing, and endpoints. - [Professional Voice Clone](https://developers.heygen.com/docs/voices/professional-voice-clone.md): Create and retrain a professional voice clone from 20+ minutes of recordings. Paid feature: each voice needs a purchased slot. Includes a copyable prompt so a coding agent can run the whole setup with a non-technical user. - [Instant Voice Clone](https://developers.heygen.com/docs/voices/heygen-voice-instant-clone.md): New. Clone a voice from one recording on the HeyGen Voice model with POST /v3/models/audio/voices mode instant; ready in seconds, no slot, free to create during the preview. Covers fields, statuses, failure reasons, languages, errors, and a copyable prompt for coding agents. - [Text to Speech](https://developers.heygen.com/docs/voices/heygen-voice-speech.md): New. Generate completed or streaming audio from an instant or professional HeyGen Voice clone with POST /v3/models/audio/tts and /tts/stream; model heygen-voice-1, expressiveness_boost for instant voices, prosody controls for professional voices. Includes a copyable prompt for coding agents. - [Browse Voices](https://developers.heygen.com/docs/voices/search-voices.md): Search and list available voices with filtering and cursor-based pagination. Use a voice_id from this endpoint when creating speech or videos. - [Design a Voice](https://developers.heygen.com/docs/voices/design-voices.md): Can't find a pre-built voice that fits? Describe the voice you want and HeyGen returns up to 3 matching options. Pick the one that fits best and use its voice_id directly in video creation or text-to-speech. - [Third Party Speech](https://developers.heygen.com/docs/voices/speech.md): Synthesize catalog voices (stock, designed) via POST /v3/voices/speech on the HeyGen Voice (default), Starfish, or ElevenLabs engine. HeyGen Voice clones use Text to Speech on POST /v3/models/audio/tts instead. - [Design a Custom Voice (CLI Recipe)](https://developers.heygen.com/design-a-voice.md): Describe the voice you want in plain English — tone, accent, personality — and get a custom voice for any video. ## Tools - [AI Clipping](https://developers.heygen.com/ai-clipping.md): Turn a long-form video into short highlight clips via POST /v3/ai-clipping — target durations, portrait/landscape/square framing, virality scores. Captions burn in by default; set output_settings.captions to false for clean footage. - [Background music](https://developers.heygen.com/background-music.md): Semantically search HeyGen's background-music catalog with a natural-language description ("upbeat lofi hip-hop") and get ranked tracks with pre-signed download URLs. - [Sound effects](https://developers.heygen.com/sound-effects.md): Semantically search HeyGen's sound-effects catalog with a natural-language description ("whoosh for a scene change") via GET /v3/audio/sounds with type=sound_effects. Returns ranked SFX with pre-signed download URLs. - [Filler word removal](https://developers.heygen.com/filler-word-removal.md): Remove filler words ("um", "uh") and overlong silences from a finished video via POST /v3/filler-word-removals — one cleaned cut back, with num_cuts and reduction_pct statistics. $0.01/sec of source video (0.01 credits/sec Enterprise), 1-minute minimum, auto-refunded when nothing changes. ## Lipsync - [Lipsync — Speed](https://developers.heygen.com/lipsync-speed.md): Replace or dub audio on an existing video with fast audio-only lip-sync. - [Lipsync — Precision](https://developers.heygen.com/lipsync-precision.md): Replace or dub audio on an existing video with high-accuracy avatar-inference lip-sync. ## Video Translation - [Video Translation — Speed](https://developers.heygen.com/docs/video-translate.md): Fast video translation with voice cloning and lip-sync across 30+ languages. - [Video Translation — Precision](https://developers.heygen.com/docs/video-translation-precision.md): Higher-quality video translation with editable proofread sessions before final render. ## On Brand - [On Brand](https://developers.heygen.com/docs/on-brand.md): Which endpoints accept a brand kit and which accept a brand glossary — Video Agent takes brand_kit_id and brand_glossary_id together; Studio, Templates, and Video Translation take brand_glossary_id. - [Brand Kits](https://developers.heygen.com/docs/brand-kits.md): Import a brand kit from a public website, poll until the import completes, read its color, logo, and font roles, and apply brand_kit_id to Video Agent output. - [Brand Glossary](https://developers.heygen.com/docs/brand-glossary.md): Create and update a glossary of pronunciations (terms), do_not_translate_terms, and forced_translations, then apply brand_glossary_id so product names are spoken correctly in generated speech and kept or replaced exactly in translation. ## Webhooks - [Webhooks](https://developers.heygen.com/docs/webhooks.md): Register and manage webhook endpoints to receive real-time notifications from HeyGen. - [Webhook Events](https://developers.heygen.com/docs/webhook-events.md): Understand the event types HeyGen can deliver and browse your event history. ## CLI The `heygen` CLI is the recommended agent surface: full API coverage, JSON output for scripting, and API-key auth for scale (`heygen auth login --api-key`, or set `HEYGEN_API_KEY`). OAuth login (`heygen auth login --oauth`) is available for a new user's first small test generations against subscription credits. - [CLI Overview](https://developers.heygen.com/cli.md): Get from zero to a generated video in minutes — right from your terminal. - [Commands](https://developers.heygen.com/commands.md): Complete command reference for the HeyGen CLI, organized by resource. - [Output Modes](https://developers.heygen.com/output-modes.md): How the CLI formats output for agents, scripts, and humans. - [Features](https://developers.heygen.com/features.md): Common flags, error handling, pagination, async polling, and CLI behaviors. - [Examples](https://developers.heygen.com/examples.md): Practical recipes for videos, TTS, avatars, translation, webhooks, and scripting. ## Agent Skills - [Skills Overview](https://developers.heygen.com/skills/overview.md): Official HeyGen skills for AI coding agents — what they are and which workflows they cover. - [Install Skills](https://developers.heygen.com/skills/install.md): Install the official skills across Claude Code, Cursor, Codex, Gemini CLI, and other agents. - [heygen-video Skill](https://developers.heygen.com/skills/heygen-video.md): Guided video generation (v3 only) with frame checks and prompt engineering. - [heygen-avatar Skill](https://developers.heygen.com/skills/heygen-avatar.md): Create and manage avatars and looks from an agent workflow. - [heygen-translate Skill](https://developers.heygen.com/skills/heygen-translate.md): Translate videos across languages from an agent workflow. ## MCP MCP is OAuth-based and bills subscription credits — the fastest path for a new user to test a one-off generation from an AI host. For scale, move the workflow to the CLI or raw API with an API key. - [MCP Overview](https://developers.heygen.com/mcp/overview.md): MCP setup overview — endpoint URL, OAuth flow, supported hosts, and the full tool reference. - [Claude Code](https://developers.heygen.com/mcp/claude-code.md): Connect HeyGen to Claude Code via the remote MCP endpoint — one-command setup, OAuth, and HeyGen skills. - [Claude Web](https://developers.heygen.com/mcp/claude-web.md): Generate AI avatar videos directly within Claude using HeyGen's remote MCP server. - [Codex CLI](https://developers.heygen.com/mcp/codex-cli.md): Connect HeyGen to OpenAI Codex CLI via the remote MCP endpoint. Covers the required `--url` flag, OAuth login, and the two setup errors it produces. - [Cursor](https://developers.heygen.com/mcp/cursor.md): Connect HeyGen to Cursor via the remote MCP endpoint. - [Gemini CLI](https://developers.heygen.com/mcp/gemini-cli.md): Connect HeyGen's Video Agent to Gemini CLI to generate AI avatar videos directly from your terminal. - [Grok](https://developers.heygen.com/mcp/grok.md): Connect HeyGen to Grok via the remote MCP endpoint. - [Lovable](https://developers.heygen.com/mcp/lovable.md): Generate HeyGen videos from Lovable apps via the remote MCP endpoint. - [Manus](https://developers.heygen.com/mcp/manus.md): HeyGen's Video Agent is available as a native tool connection in Manus — agents can script, render, and deliver videos, including on automated schedules. - [OpenAI](https://developers.heygen.com/mcp/open-ai.md): Install the HeyGen plugin in ChatGPT from the plugin directory, connect it with OAuth, and generate videos from the chat. - [Superhuman](https://developers.heygen.com/mcp/superhuman.md): Generate HeyGen videos from any web page using the HeyGen agent in Superhuman Go. ## Cookbook (Use-Case Workflows) - [Cookbook Overview](https://developers.heygen.com/overview.md): The API docs show you how to call the endpoints. The cookbook shows you what to build. - [Showcase](https://developers.heygen.com/showcase.md): Real projects built with the HeyGen API. Get inspired, then build your own. - [Social Media Content Pipeline](https://developers.heygen.com/social-media-content-pipeline.md): Batch-generate short-form videos for TikTok, Reels, and Shorts — no camera, no mic, no editing. - [Personalized Sales Outreach](https://developers.heygen.com/personalized-sales-outreach.md): Generate personalized video messages for prospects at scale — from CRM data to inbox. - [Training & Onboarding Videos](https://developers.heygen.com/training-and-onboarding-videos.md): Convert training docs, policies, and SOPs into engaging video — and keep them in sync when materials change. - [Product Demo Videos](https://developers.heygen.com/product-demo-videos.md): Generate product demos from screenshots and specs — and regenerate when your product changes. - [Multilingual Content](https://developers.heygen.com/multilingual-content.md): Create one video, translate it into 10+ languages with lip-sync — reach a global audience. - [Content Repurposing](https://developers.heygen.com/content-repurposing.md): Turn blog posts, articles, and newsletters into video — reach audiences that don't read. - [Real Estate Listing Videos](https://developers.heygen.com/real-estate-listing-videos.md): Turn property photos and listing data into narrated tour videos — for a fraction of traditional production costs. - [E-commerce Product Videos](https://developers.heygen.com/e-commerce-product-videos.md): Generate product videos from catalog data at scale — because product pages with video consistently outperform those without. - [Automated Broadcast](https://developers.heygen.com/automated-broadcast.md): Build a pipeline that generates and distributes video content on a schedule — daily news, weekly updates, recurring series. - [Docs to Video](https://developers.heygen.com/docs-to-video.md): Auto-generate video walkthroughs when your documentation changes — in CI/CD or on demand. - [Personalized Greetings & Recognition](https://developers.heygen.com/personalized-greetings-and-recognition.md): Generate personalized birthday, welcome, and recognition videos at scale — make every person feel valued. ## Video Composition - [Introduction to Hyperframes](https://developers.heygen.com/hyperframes-overview.md): What Hyperframes is — a code-driven video framework that turns HTML compositions into rendered video. Covers core concepts (compositions, data attributes, variables, deterministic rendering) and the ways to render. - [Hyperframes Cloud Rendering](https://developers.heygen.com/hyperframes.md): Render an HTML project bundle to video on HeyGen's infrastructure via POST /v3/hyperframes/renders — upload a zip, inject runtime variables, poll or use webhooks, download the MP4/WebM/MOV. - [Hyperframes Use Cases](https://developers.heygen.com/hyperframes-heygen.md): Combine an avatar video, background music, and sound effects into one finished video by compositing them in a Hyperframes render — wires POST /v3/videos, GET /v3/audio/sounds, and POST /v3/hyperframes/renders into a single pipeline. - [HeyGen Studio](https://developers.heygen.com/studio-videos.md): Compose avatar clips, images, and video footage into one rendered MP4 with a single POST /v3/videos call (type: "studio") — 1–50 whole-frame scenes, global aspect ratio/resolution/captions, all-or-nothing render. - [Video Details](https://developers.heygen.com/video-details.md): Read everything the API knows about a video you've created — delivery URLs, lifecycle timestamps, and the full scene-by-scene composition. - [HeyGen Studio Template](https://developers.heygen.com/templates.md): Discover HeyGen Studio templates and read their variable schema over the API — list API-ready templates, inspect the variables each exposes, and fill them to generate on-brand videos at scale. - [Building a Studio Template](https://developers.heygen.com/templates-guide.md): Design a reusable template in the HeyGen Studio editor — named variables, scenes, and the settings that make it API-ready. - [Create Studio Template via API](https://developers.heygen.com/create-template.md): Create a template from a video you generated with the API or saved in the HeyGen editor, and mark which parts change (avatar, voice, images, script phrases), all over the API, then generate personalized videos from it. - [Motion Graphics from a Prompt](https://developers.heygen.com/motion-graphics.md): Generate animated title cards, product launches, and visual content — no After Effects, no React, just HTML. - [Data Visualization Videos](https://developers.heygen.com/data-to-video.md): Turn datasets, metrics, and algorithms into animated videos — charts that move, dashboards that update, patterns that evolve. - [Automated Video Pipeline](https://developers.heygen.com/automated-pipeline.md): Generate videos programmatically from data — in CI/CD, on a schedule, or triggered by events. ## API Reference Auto-generated from the OpenAPI spec. Resource families are grouped below. ### Videos - [Create Video](https://developers.heygen.com/reference/create-video.md): Creates a video from a HeyGen avatar, an arbitrary image, a cinematic-avatar prompt, or a studio scene composition (type: avatar | image | cinematic_avatar | studio). Supports scripts or pre-recorded audio for lip-sync, and the Avatar III, IV, and V engines via the 'engine' field (Avatar IV by default). - [Get Video](https://developers.heygen.com/reference/get-video.md): Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable. - [List Videos](https://developers.heygen.com/reference/list-videos.md): Returns a paginated list of all videos in the account. Filterable by folder_id or title substring. - [Delete Video](https://developers.heygen.com/reference/delete-video.md): Permanently deletes a video and its associated files. This action cannot be undone. ### Templates - [List Templates](https://developers.heygen.com/reference/list-templates.md): Returns a paginated list of API-ready HeyGen Studio templates in the workspace. - [Get Template](https://developers.heygen.com/reference/get-template.md): Returns a template's variable schema (with current defaults) and its scenes. - [Generate Video from Template](https://developers.heygen.com/reference/generate-video-from-template.md): Renders a video from a template by replacing its variables (text, image, video, audio, character, voice). ### AI Clipping - [Create AI Clipping](https://developers.heygen.com/reference/create-ai-clipping.md): Starts a clipping job for a source video — target durations, aspect ratio, captions (on by default), and an optional editorial prompt. Returns an ai_clipping_id. - [Get AI Clipping](https://developers.heygen.com/reference/get-ai-clipping.md): Returns job status, live progress, and produced clips with virality scores and presigned URLs. - [List AI Clipping](https://developers.heygen.com/reference/list-ai-clipping.md): Returns a paginated list of clipping jobs. - [Delete AI Clipping](https://developers.heygen.com/reference/delete-ai-clipping.md): Permanently deletes a clipping job and its clips. ### Filler Word Removal - [Create Filler Word Removal](https://developers.heygen.com/reference/create-filler-word-removal.md): Submits a video (URL or asset_id) for filler-word and silence removal. Returns a filler_word_removal_id immediately (202); the job runs asynchronously. - [Get Filler Word Removal](https://developers.heygen.com/reference/get-filler-word-removal.md): Returns job status, progress, and — once completed — the presigned URL of the cleaned video plus removal statistics (num_cuts, reduction_pct, durations). ### Batches - [Create Video Batch](https://developers.heygen.com/reference/create-video-batch.md): Submits up to 100 video creation payloads in one call and returns a single batch_id. - [Get Video Batch](https://developers.heygen.com/reference/get-video-batch.md): Returns aggregate batch status and per-item video ids. - [Create Video Translation Batch](https://developers.heygen.com/reference/create-video-translation-batch.md): Submits up to 100 translation payloads in one call; multi-language payloads expand to one item per language. - [Create Lipsync Batch](https://developers.heygen.com/reference/create-lipsync-batch.md): Submits up to 100 lipsync payloads in one call. - [Create Asset Upload Batch](https://developers.heygen.com/reference/create-asset-upload-batch.md): Presigns up to 100 direct-to-S3 upload slots in one call; finalize with the complete-batch endpoint. - [Complete Asset Upload Batch](https://developers.heygen.com/reference/complete-asset-upload-batch.md): Finalizes every uploaded file in a batch after the upload PUTs return 200. Files are ingested independently, so one bad file does not fail the rest. Idempotent. - [Get Video Translation Batch](https://developers.heygen.com/reference/get-video-translation-batch.md): Returns aggregate batch status and one page of per-item ids and statuses. - [Get Lipsync Batch](https://developers.heygen.com/reference/get-lipsync-batch.md): Returns aggregate batch status and one page of per-item ids and statuses. - [Get Asset Batch](https://developers.heygen.com/reference/get-asset-batch.md): Returns aggregate batch status and one page of per-item ids and statuses. **Bulk status reads.** Four parallel endpoints check up to 100 ids (or whole batches) in one request, addressed by comma-separated ids and/or batch_ids. Every one of them returns each entry's id under the key `video_id` — the batch read model is shared across resources, so an asset's id also arrives as `video_id`. Unknown or unowned ids come back as `not_found` rather than an error. - [Bulk Video Statuses](https://developers.heygen.com/reference/bulk-video-statuses.md): Statuses for up to 100 videos. - [Bulk Video Translation Statuses](https://developers.heygen.com/reference/bulk-video-translation-statuses.md): Statuses for up to 100 video translations. - [Bulk Lipsync Statuses](https://developers.heygen.com/reference/bulk-lipsync-statuses.md): Statuses for up to 100 lipsyncs. - [Bulk Asset Statuses](https://developers.heygen.com/reference/bulk-asset-statuses.md): Statuses for up to 100 assets. ### Video Agent - [Create Video Agent Session](https://developers.heygen.com/reference/create-video-agent-session.md): One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. - [Get Video Agent Session](https://developers.heygen.com/reference/get-video-agent-session.md): Returns the current status, progress, video_id, and recent chat messages for a session. - [List Video Agent Sessions](https://developers.heygen.com/reference/list-video-agent-sessions.md): Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first. - [List Session Videos](https://developers.heygen.com/reference/list-session-videos.md): Returns all videos produced within a Video Agent session, sorted newest-first. - [List Video Agent Styles](https://developers.heygen.com/reference/list-video-agent-styles.md): Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech'). - [Get Session Resource](https://developers.heygen.com/reference/get-session-resource.md): Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id. - [Send Message or Request Revision](https://developers.heygen.com/reference/send-message-or-request-revision.md): Sends a follow-up message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode. - [Stop Video Agent Session](https://developers.heygen.com/reference/stop-video-agent-session.md): Halts an active agent run at its next checkpoint. Partial results are preserved. ### HyperFrames - [Create HyperFrames Render](https://developers.heygen.com/reference/create-hyperframes-render.md): Renders an HTML composition bundle to video on HeyGen infrastructure; returns a render_id to poll. - [Get HyperFrames Render](https://developers.heygen.com/reference/get-hyperframes-render.md): Returns render status and the finished video download URL. - [List HyperFrames Renders](https://developers.heygen.com/reference/list-hyperframes-renders.md): Returns a cursor-paginated list of renders in the account, newest first. - [Delete HyperFrames Render](https://developers.heygen.com/reference/delete-hyperframes-render.md): Soft-deletes a render; subsequent GETs return 404. ### Avatars - [Create Avatar](https://developers.heygen.com/reference/create-avatar.md): Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. - [Create Avatar Consent](https://developers.heygen.com/reference/create-avatar-consent.md): Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation. - [Get Avatar Group](https://developers.heygen.com/reference/get-avatar-group.md): Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status. - [List Avatar Groups](https://developers.heygen.com/reference/list-avatar-groups.md): Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership. - [Get Avatar Look](https://developers.heygen.com/reference/get-avatar-look.md): Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status. - [List Avatar Looks](https://developers.heygen.com/reference/list-avatar-looks.md): Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video. - [Update Avatar Look](https://developers.heygen.com/reference/update-avatar-look.md): Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types. - [Delete Avatar Look](https://developers.heygen.com/reference/delete-avatar-look.md): Deletes a photo avatar, digital twin, or kit-based look. Deleting the last look in a group also deletes the parent group, after which that group id returns 404. Studio avatar looks cannot be deleted over the API. - [Delete Avatar Group](https://developers.heygen.com/reference/delete-avatar-group.md): Permanently deletes an avatar group and all its looks. Public and community groups cannot be deleted. ### Voices - [List Voices](https://developers.heygen.com/reference/list-voices.md): Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint. - [Get Voice](https://developers.heygen.com/reference/get-voice.md): Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'. - [Clone a Voice](https://developers.heygen.com/reference/clone-a-voice.md): Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is 'complete'. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos. - [Design a Voice](https://developers.heygen.com/reference/design-a-voice.md): Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results. - [Delete a Voice](https://developers.heygen.com/reference/delete-a-voice.md): Deletes a voice clone you own, freeing a slot against your clone limit. The voice must not be in use by a template. Deleting an unknown or already-deleted voice returns 404 `voice_not_found`, so a delete-then-list flow should treat that 404 as success. - [Generate Speech](https://developers.heygen.com/reference/generate-speech.md): Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps. ### Lipsync - [Create Lipsync](https://developers.heygen.com/reference/create-lipsync.md): Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync. - [Get Lipsync](https://developers.heygen.com/reference/get-lipsync.md): Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable. - [List Lipsyncs](https://developers.heygen.com/reference/list-lipsyncs.md): Returns a paginated list of all lipsync jobs in the account. - [Update Lipsync](https://developers.heygen.com/reference/update-lipsync.md): Updates the display title of a lipsync job. - [Delete Lipsync](https://developers.heygen.com/reference/delete-lipsync.md): Permanently deletes a lipsync job and its associated files. This action cannot be undone. ### Video Translation - [Create Video Translation](https://developers.heygen.com/reference/create-video-translation.md): Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality. - [Get Video Translation](https://developers.heygen.com/reference/get-video-translation.md): Returns details for a translation job including status, output language, video_url, and failure info if applicable. - [List Video Translations](https://developers.heygen.com/reference/list-video-translations.md): Returns a paginated list of all video translation jobs in the account. - [List Supported Translation Languages](https://developers.heygen.com/reference/list-supported-translation-languages.md): Returns all supported target language names for video translation. - [Update Video Translation](https://developers.heygen.com/reference/update-video-translation.md): Updates the display title of a video translation job. - [Delete Video Translation](https://developers.heygen.com/reference/delete-video-translation.md): Permanently deletes a video translation and its associated files. This action cannot be undone. ### Proofread Sessions - [Create Proofread Session](https://developers.heygen.com/reference/create-proofread-session.md): Creates a proofread session that extracts editable subtitles from a video before final rendering. - [Get Proofread Session](https://developers.heygen.com/reference/get-proofread-session.md): Returns the status and details of a proofread session. - [Download Proofread SRT](https://developers.heygen.com/reference/download-proofread-srt.md): Returns presigned download URLs for the edited and original SRT files of a completed proofread session. - [Upload Proofread SRT](https://developers.heygen.com/reference/upload-proofread-srt.md): Replaces the proofread subtitles with an edited SRT file. - [Generate Video from Proofread](https://developers.heygen.com/reference/generate-video-from-proofread.md): Starts final video generation using the approved subtitles from a proofread session. ### Webhooks - [Create Webhook Endpoint](https://developers.heygen.com/reference/create-webhook-endpoint.md): Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation — store it securely. - [List Webhook Endpoints](https://developers.heygen.com/reference/list-webhook-endpoints.md): Returns a paginated list of registered webhook endpoints. - [Update Webhook Endpoint](https://developers.heygen.com/reference/update-webhook-endpoint.md): Updates the URL and/or subscribed event types for a webhook endpoint. The events array is fully replaced — include all types you want to keep. - [Delete Webhook Endpoint](https://developers.heygen.com/reference/delete-webhook-endpoint.md): Permanently removes a webhook endpoint. Events will no longer be delivered to this URL. This action cannot be undone. - [Rotate Webhook Signing Secret](https://developers.heygen.com/reference/rotate-webhook-signing-secret.md): Generates a new signing secret for a webhook endpoint and immediately invalidates the old one. Store the new secret securely — it will not be shown again. - [List Webhook Event Types](https://developers.heygen.com/reference/list-webhook-event-types.md): Returns all available webhook event types with human-readable descriptions. - [List Webhook Events](https://developers.heygen.com/reference/list-webhook-events.md): Returns a paginated history of delivered webhook events. Filterable by event_type or entity_id. ### Assets - [Upload Asset](https://developers.heygen.com/reference/upload-asset.md): Uploads a file (image, video, audio, or PDF) and returns an asset_id for use in other endpoints. Max 32 MB. Supported types: png, jpeg, mp4, webm, mp3, wav, pdf. - [Create Asset Upload](https://developers.heygen.com/reference/create-asset-upload.md): Presigns a direct-to-S3 upload slot for large files; finalize with Complete Asset Upload. - [Complete Asset Upload](https://developers.heygen.com/reference/complete-asset-upload.md): Finalizes a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent — repeated calls return the same asset. - [Get Asset](https://developers.heygen.com/reference/get-asset.md): Returns an asset's metadata — owner, upload timestamp, file type, and a publicly accessible URL. - [Delete Asset](https://developers.heygen.com/reference/delete-asset.md): Permanently deletes an asset in the caller's workspace. ### Audio - [Search Audio (Music or Sound Effects)](https://developers.heygen.com/reference/search-audio-music-or-sound-effects.md): Semantically searches the audio catalog by natural-language description — `type=music` (default) for background beds like 'upbeat lofi hip-hop', or `type=sound_effects` for SFX like 'whoosh for a scene change'. Returns tracks ranked by similarity, each with a pre-signed download URL. ### Brand - [Create Brand Kit](https://developers.heygen.com/reference/create-brand-kit.md): Imports logos, colors, and fonts from a public website URL and returns a brand_kit_id with status loading. - [Get Brand Kit](https://developers.heygen.com/reference/get-brand-kit.md): Returns one brand kit with its colors, logos, fonts, and role assignments, plus the import status. - [List Brand Kits](https://developers.heygen.com/reference/list-brand-kits.md): Returns the brand kits in the workspace, each with its colors and logo URL. - [Update Brand Kit](https://developers.heygen.com/reference/update-brand-kit.md): Renames a brand kit or reassigns which color, logo, and font play which role; each role object is replaced in full. - [Delete Brand Kit](https://developers.heygen.com/reference/delete-brand-kit.md): Permanently deletes a brand kit along with the colors, logos, and fonts it holds. - [Create Brand Glossary](https://developers.heygen.com/reference/create-brand-glossary.md): Creates a brand glossary from a workspace-unique name and optional terms (pronunciations), do_not_translate_terms, and forced_translations. - [Update Brand Glossary](https://developers.heygen.com/reference/update-brand-glossary.md): Replaces a brand glossary's name, terms, do_not_translate_terms, or forced_translations in full; an omitted field is left unchanged. - [List Brand Glossaries](https://developers.heygen.com/reference/list-brand-glossaries.md): Returns the brand glossaries in the workspace with their names and timestamps. - [Get Brand Glossary](https://developers.heygen.com/reference/get-brand-glossary.md): Returns one brand glossary with its full terms list plus do_not_translate_terms and forced_translations when present. ### Account - [Get Current User](https://developers.heygen.com/reference/get-current-user.md): Returns the authenticated user's profile, remaining credits or balance, and billing details. ## OpenAPI Specs - [external-api](https://developers.heygen.com/openapi/external-api.json) - [openapi](https://developers.heygen.com/openapi.yaml)