HeyGen API

Generates complete talking-head videos from a single natural language text prompt without requiring explicit avatar or voice selection. The Video Agent model (v3) uses an autonomous decision-making pipeline that selects appropriate avatars, voices, gestures, and pacing automatically, then synthesizes the final video asynchronously at $0.0333/second. This eliminates the need for users to manage avatar/voice configuration, making it ideal for rapid prototyping and high-volume automated video generation workflows.

Converts a single still photograph of a person's face into an animated talking-head avatar that can deliver scripts with synchronized lip movements and natural gestures. The Photo Avatar capability uses Avatar IV model to perform face detection, 3D facial mesh reconstruction, and real-time animation synthesis, then applies the Starfish TTS engine to generate audio and lip-sync it to the animated face. Processing is asynchronous and billed at $0.05/second of generated video, supporting 175+ languages for voice output.

Integrates with the Model Context Protocol (MCP) to enable AI agents and LLMs to call HeyGen capabilities as tools within their reasoning loops. MCP integration allows language models to autonomously decide when to generate videos, select appropriate parameters, and handle results as part of multi-step reasoning tasks. Specific MCP schema, tool definitions, and integration details are not documented; only mentioned as available alongside 'Agentic CLI' and 'Skills'.

Implements a granular pay-as-you-go billing model where each HeyGen capability is priced per second of generated or processed video/audio, with quality/latency tradeoffs available for some operations. Video Agent costs $0.0333/sec, Photo Avatar $0.05/sec, Digital Twin $0.0667/sec, and translation/lipsync operations offer Speed ($0.0333/sec) and Precision ($0.0667/sec) variants. Starfish TTS is the cheapest at $0.000667/sec. Minimum entry point is $5, but free tier limits and volume discounts are undocumented. Billing is per-second of output, not per-request, enabling transparent cost prediction for high-volume workflows.

Supports video generation, translation, and voice synthesis across 175+ languages, enabling global content distribution without manual localization. Language support is built into Photo Avatar, Digital Twin, Video Translation, and Starfish TTS capabilities. Video Translation specifically supports 40+ languages for audio-only dubbing and 175+ languages with lip-sync, suggesting different language coverage for different features. Automatic language selection and detection mechanisms are unknown; users must explicitly specify target language.

Creates a hyper-realistic digital twin avatar trained from video footage of a real person, enabling that person's likeness to deliver scripts in any language with natural gestures and expressions. The Digital Twin model uses the provided video footage to learn facial characteristics, movement patterns, and micro-expressions, then synthesizes new videos where the trained avatar delivers arbitrary scripts. Processing is asynchronous at $0.0667/second, supporting 175+ languages for voice output via Starfish TTS with automatic lip-sync to the synthesized video.

Translates existing videos into 175+ languages with automatic lip-sync adjustment, supporting two processing variants: Speed ($0.0333/second) for faster turnaround with acceptable quality, and Precision ($0.0667/second) for higher-quality lip-sync and natural-sounding dubbing. The translation pipeline uses Starfish TTS to generate dubbed audio in the target language, then applies the Lipsync capability to re-synchronize mouth movements to the new audio. This enables global video distribution without re-recording talent or managing multiple video versions.

Re-synchronizes lip movements in an existing video to match replacement audio, enabling use cases like audio replacement, voice actor changes, or accent correction without re-recording video. The Lipsync capability analyzes the original video's mouth movements and facial structure, then applies generative animation to adjust lip-sync to the new audio track. Two variants are available: Speed ($0.0333/second) for acceptable quality with faster processing, and Precision ($0.0667/second) for higher-quality mouth movement synthesis. This is a core component of the Video Translation pipeline but can also be used independently.

Generates natural-sounding audio voiceovers from text using the Starfish TTS engine, supporting 175+ languages with configurable voice characteristics. The Starfish model is integrated throughout HeyGen's pipeline (Photo Avatar, Digital Twin, Video Translation) but can also be called independently via the `/v3/voices` endpoint to generate standalone audio files. Processing is asynchronous and billed at $0.000667/second of generated audio, making it the lowest-cost component of the HeyGen API. Output audio can be used for video dubbing, voiceover replacement, or standalone audio content.

Manages asynchronous video and audio generation jobs through a polling-based status tracking model where API calls return a job ID immediately, and clients poll the API to check job status and retrieve completed outputs. All HeyGen capabilities (Video Agent, Photo Avatar, Digital Twin, Translation, Lipsync, Voices) operate asynchronously; there is no streaming or real-time output. The polling mechanism enables long-running video synthesis operations without blocking client connections, but requires clients to implement retry logic and handle job timeouts. Job status and completion time are unknown; documentation does not specify SLAs or maximum processing duration.

Authenticates all API requests using an API key passed in the `x-api-key` HTTP header, with keys issued through the HeyGen developer portal. This is a stateless, header-based authentication scheme that requires no session management or token refresh logic. API keys are tied to a developer account and control access to all HeyGen capabilities; there is no per-endpoint or per-capability permission granularity documented. Key rotation, expiration, and revocation mechanisms are unknown.

Provides a JavaScript/Node.js SDK that wraps the REST API and abstracts HTTP details, returning structured JSON responses for all operations. The SDK handles request serialization, response parsing, and error handling, reducing boilerplate code compared to raw HTTP calls. Code examples show SDK usage for creating videos with minimal configuration (passing prompt, avatar_id, voice_id), but full SDK documentation and method signatures are not provided. SDK maturity, version stability, and feature parity with REST API are unknown.

Provides a command-line interface (HeyGen CLI) designed for agent-first workflows and automation, with all commands returning structured JSON output suitable for parsing by scripts, CI/CD pipelines, and autonomous agents. The CLI wraps the full v3 API and is designed to be composable with other tools via shell pipes and JSON parsing. Documentation mentions 'Agentic CLI' design but specific commands, usage examples, and output schemas are not provided. CLI is positioned as the primary interface for programmatic workflows alongside the REST API.