Skills
HeyGen AI agent skills — avatar creation and video production via the v3 Video Agent pipeline
Last verified:
What is Skills?
Skills HeyGen's Developer API is a programmatic platform for generating AI avatar videos, translating videos into 30+ languages, and creating interactive streaming avatar sessions. The flagship Video Agent feature lets developers generate complete MP4 videos from a single text prompt—the AI automatically selects the avatar, voice, script, and visual style, then renders the video in 1-5 minutes. The API supports v3 endpoints with exclusive access to new capabilities like the CLI, MCP Server, Voice design API, and latest models including lipsync.
Key features include one-shot prompt-to-video generation, multi-scene video creation with precise control over avatars and voices, video translation with natural voice cloning and lip-sync, template-based video customization, real-time streaming avatars for interactive sessions, webhook notifications for async completion, and tools like the CLI and MCP Server for AI agent integration. Developers can upload assets (images, videos, audio, PDFs), design custom voices with text descriptions, and use cursor-based pagination for listing videos, avatars, and voices.
This tool is designed for developers building applications that need automated video generation—such as sales teams creating personalized outreach videos, marketing teams producing social media content at scale, HR teams generating training and onboarding videos, e-commerce companies creating product demos from catalogs, real estate agents producing property tours, and media companies automating broadcasts. It serves businesses wanting to integrate AI video into CI/CD pipelines, create multilingual content for global audiences, and repurpose blogs/docs into ready-to-publish video without manual production.
Skills pricing
Pricing model: Freemium
HeyGen uses a self-serve Pay-As-You-Go model with no monthly subscription or commitments. You purchase USD balance when needed and usage is deducted from your prepaid wallet. No credit card required for free tier. Video Agent (prompt-to-video) costs $0.0333/second. Photo Avatar generation at 720p/1080p costs $0.05/second, at 4K costs $0.0667/second. Digital Twin and Studio Avatar cost $0.0667/second at 720p/1080p, $0.0833/second at 4K. Video Translation Speed mode (audio only) is $0.0167/second, Speed mode with lip-sync is $0.0333/second, Precision mode with lip-sync is $0.0667/second. Lipsync Speed is $0.0333/second, Precision is $0.0667/second. Text-to-Speech (Starfish model) is $0.000667/second. Digital Twin and Photo Avatar creation costs $1.00 per call. Pay-As-You-Go plan includes 10 max concurrent video jobs.
Skills pros
- Generate complete videos from a single text prompt with Video Agent
- No web app required—fully programmatic API workflow
- Translates videos into 30+ languages with voice cloning and lip-sync
- v3 API provides exclusive access to latest features like CLI and MCP
- Webhook support eliminates polling—get notified on completion
- Up to 10 concurrent video jobs on Pay-As-You-Go plan
- Supports uploading up to 20 file attachments (images, video, audio, PDF)
- Design custom voices instantly using plain English descriptions
- Photo-to-video feature turns single headshots into talking avatars
- Output videos in 1080p default, with 720p/4K options available
- Both landscape (16:9) and portrait (9:16) aspect ratios supported
- MCP Server connects HeyGen to AI agents and copilots seamlessly
- CLI enables scripting video creation directly from terminal
- Proofread mode available for editing subtitles before final generation
- Cursor-based pagination for efficient listing of videos and avatars
- Async generation with status polling (pending→processing→completed)
- Instant avatars supported in Template V2 API for customization
Skills cons
- Legacy v1/v2 endpoints deprecated after October 31, 2026—must migrate
- Video generation is asynchronous—requires polling or webhook setup
- Rate limiting returns 429 errors with Retry-After header on excess
- Free tier has usage quotas that can be exceeded requiring plan upgrade
- API key cannot be viewed again after initial generation—must rotate
- Maximum 5,000 characters for script text limits long-form content
- Input video files must be under 100 MB and under 2K resolution
- OAuth authentication bills against web plan instead of API tier
- Avatar III only available to existing customers—not for new users
- Proofread mode restricted to Enterprise plans only
Frequently asked questions about Skills
How do I get my HeyGen API key?
Go to the HeyGen dashboard at app.heygen.com/home?from=&nav=API, click to generate your API key, and save it immediately—you cannot view it again after closing. The key is used in the X-Api-Key header for all API requests. For best practices including rotation and OAuth, see the API Key guide in the documentation.
What is the Video Agent and how does it work?
Video Agent is HeyGen's one-shot prompt-to-video feature. Send a text prompt (1-10,000 characters) describing your video, and the AI automatically handles scripting, avatar selection, voice choice, scene composition, and rendering. The session returns a session_id immediately with status 'generating', then you poll for the video_id and eventually get a completed MP4 URL. Most videos complete in 1-5 minutes.
Do I need to poll for video completion or can I use webhooks?
You can use webhooks instead of polling. Pass a callback_url in your video creation request to receive a POST notification when the video completes or fails. The callback_id you provide is echoed back in the webhook payload for correlation. In production, webhooks are recommended over polling. If you must poll, use exponential backoff and respect the Retry-After header on 429 errors.
What file types can I attach to Video Agent requests?
You can attach up to 20 files including images (PNG, JPEG), videos (MP4, WebM), audio (MP3, WAV), and PDFs. Files can be provided as asset_id (from POST /v3/assets upload), HTTPS URL, or base64-encoded content. The URLs must be publicly accessible without authentication. Maximum file size for asset upload is 32 MB.
What's the difference between Speed and Precision mode for video translation?
Speed mode is faster and best for quick turnaround, batch jobs, and workflows where time matters more than perfect lip-sync. It provides adequate translation with standard lip-sync quality. Precision mode is slower but provides context- and gender-aware translation with high-quality lip-sync, best for faces with significant movement, side angles, occlusions, or final delivery videos. Precision costs $0.0667/second vs Speed's $0.0333/second with lip-sync.
How do I authenticate API requests?
All HeyGen API requests authenticate via the X-Api-Key header containing your API token. The base URL is https://api.heygen.com. The API supports v1, v2, and v3 versions (v3 is recommended for new integrations). For OAuth-based authentication, note that OAuth bearer tokens bill against your web plan instead of the API tier—API key authentication is recommended for automation and provides higher concurrency limits.
What are the concurrency limits and rate limits?
Pay-As-You-Go plan allows 10 max concurrent video jobs, including Video Agent sessions, avatar video renders, and video translations. Exceeding this returns 429 Too Many Requests with a Retry-After header. All endpoints enforce rate limits—when exceeded, you get 429 with Retry-After indicating seconds to wait. Use exponential backoff for retries. Most list endpoints support pagination with limit parameter (default 10-20, max 50-100 depending on endpoint).
What output video specifications does HeyGen support?
Output videos have 25 fps for avatar-containing videos, resolution between 128-4096 pixels width/height (default 1080p), aspect ratios of 16:9 or 9:16, maximum 50 scenes per video, and maximum 30 minutes duration. Video input must be MP4/WebM under 100 MB and under 2K resolution. Image input is JPG/PNG under 50 MB under 2K. Audio input is WAV/MP3 under 50 MB. Script text max is 5,000 characters, audio input max is 10 minutes.
What error codes should I handle in my integration?
Key error codes include: unauthorized (401) for invalid/expired API key, forbidden (403) for insufficient permissions, insufficient_credit (402) for not enough wallet balance, rate_limit_exceeded (429) for too many requests, quota_exceeded (429) for free-tier limit exceeded, video_not_found (404) for invalid video ID, download_failed (400) for inaccessible URLs, content_policy_violation (400) for policy breaches, and internal_error (500) for server issues. Each error includes machine-readable code, human-readable message, and doc_url.
Can I create custom voices and what does it cost?
Yes, you can design custom voices instantly using plain English descriptions via the CLI recipe 'Design a Custom Voice'. The Voice design API is available exclusively on v3 endpoints. For Text-to-Speech using the Starfish model, the cost is $0.000667/second. You can also apply a brand_voice_id to translations for consistent branding once set up. Cloned voices must finish processing before use, and voice_unavailable errors occur if a clone fails or expires.