HeyGen API

Converts text scripts into synchronized talking-head videos by processing input text through a speech synthesis pipeline, then mapping phoneme timing to pre-recorded avatar mouth shapes and head movements. The system uses deep learning models to match lip movements to audio in real-time, supporting 175+ languages with automatic language detection and phoneme-to-viseme mapping for accurate mouth synchronization across diverse linguistic phonetic systems.

Provides a library of pre-built digital avatars with configurable appearance parameters including clothing, background, lighting, and presentation style. The API allows selection from dozens of pre-recorded avatars or creation of custom avatars through a separate training pipeline, with styling applied at video generation time through parameter overrides that modify avatar appearance without regenerating the underlying motion capture data.

Sends webhook notifications for key video generation lifecycle events (generation_started, generation_completed, generation_failed) to a developer-specified endpoint. Webhooks include event type, video metadata, and timestamp, with automatic retry logic for failed deliveries (exponential backoff, up to 5 retries). Developers can filter events by type and configure retry behavior through dashboard settings.

Provides API endpoints to retrieve detailed metadata about generated videos including generation timestamp, avatar used, script content, language, duration, and file size. Analytics endpoints return aggregated metrics (videos generated per day, average generation time, language distribution) for monitoring usage patterns and pipeline performance. Metadata is queryable by video_id, date range, or avatar to support reporting and analytics 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.

Synthesizes natural-sounding speech from text input in 175+ languages using neural text-to-speech models with automatic language detection and per-language voice selection. The system applies language-specific prosody rules, intonation patterns, and phonetic processing to generate speech that matches native speaker patterns, with support for SSML markup to control speech rate, pitch, emphasis, and pauses for fine-grained audio customization.

Processes multiple video generation requests asynchronously through a queue-based system, allowing developers to submit batches of scripts and receive completion notifications via webhook callbacks. The API returns job IDs immediately and polls or subscribes to status updates, enabling efficient handling of large-scale video production workflows without blocking on individual video rendering times.

Enables dynamic script generation by accepting template variables and substitution rules that are applied at video generation time, allowing creation of personalized videos with custom names, dates, or dynamic content without regenerating the entire video. The system supports variable interpolation, conditional text blocks, and template rendering to produce unique videos from a single avatar and script template.

Allows specification of output video quality parameters including resolution (720p, 1080p, 4K), bitrate, frame rate, and codec settings at generation time. The API applies quality settings during video encoding without requiring separate post-processing, enabling optimization for different distribution channels (social media, broadcast, streaming) with appropriate quality-to-file-size tradeoffs.

Delivers generated videos through a CDN with automatic URL expiration and optional permanent storage. The API returns temporary signed URLs (typically valid for 24-48 hours) for immediate video access, with options to request permanent storage or direct download. This architecture reduces storage costs by defaulting to temporary delivery while enabling long-term archival when needed.

Implements rate limiting and quota management to control API usage, with different tiers providing varying request rates and monthly video generation quotas. The API returns rate limit headers indicating remaining requests and quota, enabling developers to implement backoff logic and quota tracking. Quota resets monthly and can be monitored through dashboard or API endpoints.

Provides detailed error responses with specific error codes, diagnostic messages, and remediation suggestions for common failure scenarios (invalid script, unsupported language, quota exceeded). The API returns structured error objects with error_code, message, and suggested_action fields, enabling developers to implement targeted error handling and user-facing error messages without parsing error text.

Supports API key authentication for direct API calls and OAuth 2.0 for third-party integrations and user-delegated access. API keys are managed through the dashboard with granular permission scopes (video_generation, video_retrieval, account_management), and OAuth tokens enable secure delegation without sharing API keys. Both authentication methods support token rotation and revocation for security.