# 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: 1. **MCP** — if `mcp__heygen__*` tools are visible, use them directly. OAuth, no key handling, no separate billing. See [MCP Overview](https://developers.heygen.com/mcp/overview.md). 2. **CLI** — if `heygen` is on PATH and `heygen auth status` returns an account, drive the workflow via [`heygen` commands](https://developers.heygen.com/commands.md). 3. **Raw API** — only if neither is wired up. 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. 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). ## Getting Started - [For AI Agents](https://developers.heygen.com/docs/for-ai-agents.md): Agent-first onboarding — auth-detection ladder (MCP → CLI → raw API), 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. - [Choosing the Right Video API](https://developers.heygen.com/docs/choosing-the-right-video-api.md): Compare Video Agent and direct video creation to pick the right approach for your use case. - [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 - [API Key](https://developers.heygen.com/docs/api-key.md): Generate, rotate, and secure your HeyGen API key. - [OAuth 2.0](https://developers.heygen.com/docs/connecting-your-app-to-heygen-with-oauth-20.md): Securely integrate your application with HeyGen using OAuth 2.0. ## 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://developers.heygen.com/docs/pricing.md): Per-operation pricing for self-serve API plans. - [Enterprise Pricing](https://developers.heygen.com/docs/enterprise-pricing.md): Pricing model overview for HeyGen Enterprise contracts. - [Enterprise Billing — Dollar-Based](https://developers.heygen.com/docs/enterprise-pricing-dollar-base.md): HeyGen offers two Enterprise billing models depending on your contract. Your account team will help you choose the right fit. - [Usage Limits](https://developers.heygen.com/docs/usage-limits.md): Rate limits, concurrency, and quota behavior across HeyGen API endpoints. ## 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 - [Video Agent Overview](https://developers.heygen.com/docs/overview.md): Generate videos with a single prompt using the Video Agent API. No web app required. - [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. - [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. - [Interactive Sessions](https://developers.heygen.com/docs/interactive-sessions.md): Review storyboards, send follow-up messages, and iterate with the Video Agent before generating. - [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`. - [Models](https://developers.heygen.com/models.md): Avatar types (digital twin, photo, studio, image, prompt) and rendering engines (Avatar III, IV, V) with capabilities, supported features, and migration guidance. - [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. - [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. - [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. - [Assets](https://developers.heygen.com/assets.md): Upload files for use across the HeyGen API. ## Avatars - [Create Avatar](https://developers.heygen.com/docs/create-avatar.md): Create a new avatar from your own footage, images, or a text description. 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. - [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. - [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. - [Text to Speech](https://developers.heygen.com/docs/voices/speech.md): If you want to generate audio from text without creating a video, HeyGen offers a dedicated TTS engine called Starfish. Pass a script and a compatible voice ID — get back an audio file URL. - [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. - [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. ## 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. - [Bulk Video Translation](https://developers.heygen.com/docs/bulk-video-translation.md): When you need to translate many videos at once (e.g., localizing a content library), you can script against the API using a CSV as input. This guide walks through a Python script that reads a CSV of videos, submits translation requests to the v3 API, and writes the results to a new CSV. ## 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 - [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. ## MCP - [MCP (Top-Level)](https://developers.heygen.com/mcp.md): Connect HeyGen video generation to any MCP-compatible AI agent — tools reference, capabilities, billing model. - [MCP Overview](https://developers.heygen.com/mcp/overview.md): MCP setup overview — endpoint URL, OAuth flow, and supported hosts. - [Claude Code](https://developers.heygen.com/mcp/claude-code.md): Connect HeyGen to Claude Code via the remote MCP endpoint — config, OAuth, and HeyGen skills setup. - [Claude Web](https://developers.heygen.com/mcp/claude-web.md): Generate AI avatar videos directly within Claude using HeyGen's remote MCP server. - [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. Once configured, Gemini can script, render, and deliver videos through natural-language prompts as part of your development workflow. - [Manus](https://developers.heygen.com/mcp/manus.md): HeyGen's Video Agent is available as a native tool connection in Manus. Once connected, Manus agents can generate fully scripted and rendered AI avatar videos — including on automated schedules — without any manual editing or production workflow. - [OpenAI](https://developers.heygen.com/mcp/open-ai.md): Connect HeyGen to OpenAI agents and assistants via the remote MCP endpoint. - [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. ## Hyperframes (HTML-to-Video) - [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. ## Legacy APIs - [Studio API](https://developers.heygen.com/studio-api.md): Generate videos using the AI Studio backend with support for avatars, voices, and dynamic backgrounds. - [Template API](https://developers.heygen.com/template-api.md): Generate a video based on a specified template, including scene IDs and dynamic variable replacements. - [More Legacy APIs](https://developers.heygen.com/more-legacy-api.md): Reference index for older v1/v2 endpoints still supported until October 31, 2026. ## 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 or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar IV engine and the upcoming Avatar V, while Avatar III video generation requires the legacy API (v1 or v2). - [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. ### 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. ### 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. ### 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. - [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. ### 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)