Automated avatar-video production
Generate repeatable onboarding, product, training, or campaign videos from approved scripts and structured inputs.
Independent tool overview
HeyGen CLI at a glance
HeyGen CLI is an official command-line client for automating HeyGen avatar videos, translation, and lip sync through the v3 API. It is useful for scripts and agents, but every production workflow still needs secure credential handling, asynchronous job checks, output review, and API-cost controls.
Visit the official HeyGen CLI site ↗
- Best for
- Scripted and agent-driven HeyGen video workflows
- API
- Wraps HeyGen v3
- Default output
- Structured JSON
- Platforms
- macOS and Linux; Windows via WSL
- Authentication
- API key or OAuth
- Starting API balance
- $5 pay as you go
Overview
What HeyGen CLI is
HeyGen CLI brings HeyGen's video platform into terminals, scripts, continuous-integration jobs, containers, and AI-agent workflows. It wraps the v3 API and returns structured JSON by default, so a program can create a video, capture its ID, poll the job, and download the completed asset without driving the web editor.
Users can generate a complete prompted video through Video Agent or send a detailed JSON body that selects an avatar, voice, script, and other parameters. The CLI also covers video translation and lip sync, exposes request schemas without authentication, and offers blocking or asynchronous job handling.
The CLI itself does not have a separate subscription. API-key authentication draws from HeyGen's prepaid API wallet, which starts with a $5 top-up and is separate from normal web-plan credits. OAuth can instead bill supported usage to an eligible web plan. This distinction matters when estimating automation costs.
Use cases
Who HeyGen CLI is best for
The strongest fit depends on the job you need the product to complete, not the size of its feature list.
Agent and CI workflows
Use JSON output, exit codes, environment-based authentication, and polling to integrate video generation into programmatic jobs.
Localization pipelines
Submit translations or lip-sync jobs, track their status, and download completed localized assets without manual editor work.
Capabilities
Core HeyGen CLI features
Prompt-to-video command
Video Agent can choose an avatar, voice, and layout from one prompt, then return a session and video ID while generation continues.
Detailed JSON requests
The lower-level video command accepts structured bodies for developers who need explicit control over avatar, voice, script, and other fields.
Agent-friendly output
Structured JSON is the default, with additional output modes for streaming, readable terminal output, and machine processing.
Asynchronous job control
Create commands can return immediately for polling or wait until completion with a configurable timeout and documented exit behavior.
Translation and lip sync
The CLI exposes HeyGen's video translation and lip-sync capabilities alongside avatar-video creation.
Schema discovery
Commands can print their request schema without authentication, helping scripts and agents build valid payloads.
Process
How the HeyGen CLI workflow works
Step 1
Install and inspect
Install the single binary, verify its version, and inspect the request schema for the exact command you plan to automate.
Step 2
Authenticate securely
Use OAuth interactively or inject the API key through a managed secret in CI; never commit credentials or paste them into logged commands.
Step 3
Submit a bounded job
Use Video Agent for a prompt-led result or a structured JSON body when avatar, voice, script, and layout must be deterministic.
Step 4
Poll, validate, and download
Handle pending, processing, completed, and failed states, then review the rendered video before it enters a customer-facing pipeline.
Cost
HeyGen CLI pricing and free plan
HeyGen CLI uses the API or eligible web-plan balance rather than a CLI-specific fee. API-key workflows are prepaid pay as you go with a $5 minimum top-up. Rates are based on output duration or operation type, and the API wallet is separate from normal HeyGen web-plan credits.
Pay-As-You-Go API
Starts with a $5 wallet top-up
The self-serve option for CLI automation using an API key, with no monthly API subscription.
- Video Agent: $0.0333 per output second
- Avatar III Digital Twin or Studio Avatar: $0.0167 per second at 720p/1080p
- Avatar IV Photo Avatar: $0.05 per second at 720p/1080p
- Avatar IV Digital Twin or Studio Avatar: $0.0667 per second at 720p/1080p
Translation and lip sync
$0.0333-$0.0667 per second
Duration-based rates for localizing or lip-syncing existing video.
- Speed translation with audio only or lip sync: $0.0333 per second
- Precision translation with lip sync: $0.0667 per second
- Lipsync Speed: $0.0333 per second
- Lipsync Precision: $0.0667 per second
Other API operations
Usage based
Additional commands can have their own unit rate.
- Text-to-speech: $0.000667 per second
- Digital Twin creation: $1 per call
- Photo Avatar creation: $1 per call
- Cinematic Avatar: $7 per video
Enterprise API
Custom
For organizations that need negotiated scale, support, or restricted endpoints.
- Customized scalability
- Dedicated developer support
- Discounted rates
- Digital Twin creation and Proofread API access
Pricing checked . Check current pricing at the source ↗
Assessment
HeyGen CLI strengths and limitations
Where it stands out
- Official client for HeyGen rather than an unofficial wrapper.
- Structured JSON and documented exit behavior fit scripts, CI jobs, and agents.
- Supports both high-level prompt generation and lower-level structured control.
- Asynchronous operation prevents long renders from blocking an entire workflow.
- Pay-as-you-go API access avoids requiring a separate monthly web subscription.
- Request-schema discovery makes command integration easier to validate.
What to consider
- The CLI is only an interface; all generation still incurs HeyGen API or web-plan usage.
- Windows is not natively supported yet, so Windows users need WSL.
- Rendered video is asynchronous and can fail, time out, or require retry logic.
- API-key wallet funds and web-plan credits are separate billing pools.
- Automated prompt-to-video output can choose unsuitable scripts, visuals, voices, or layouts without review.
- Credentials stored locally or injected into automation require careful permissions, rotation, masking, and secret management.
- Custom avatars, voices, translated content, and likenesses require appropriate consent and usage rights.
- Enterprise-only features and higher-volume requirements may need a sales agreement.
Compare
HeyGen CLI alternatives
The right alternative depends on the specific output, workflow, controls and budget your project requires.
Content Creator
HeyGen Video Agent
Choose the web-based HeyGen Video Agent when a conversational visual workflow matters more than terminal automation.
Explore HeyGen Video Agent →Marketing
LiveAvatar by HeyGen
Use HeyGen's main creation experience when editors and marketers need a graphical interface rather than scripts.
Explore LiveAvatar by HeyGen →Marketing
Synthesia
Consider Synthesia for a mature browser-based enterprise avatar-video workflow with governance and collaboration features.
Explore Synthesia →Content Creator
tavus
Consider Tavus when personalized video or real-time conversational video APIs are the central requirement.
Explore tavus →Questions
HeyGen CLI FAQs
What is HeyGen CLI?
HeyGen CLI is HeyGen's official command-line client for its v3 video API. It lets developers and agents create, translate, lip-sync, monitor, and download video assets from scripts or terminals.
Is HeyGen CLI free?
The binary has no separate listed fee, but generated work consumes HeyGen API balance or eligible web-plan credits. Self-serve API access starts with a $5 pay-as-you-go wallet top-up.
How much does HeyGen Video Agent cost through the CLI?
With API-key billing, HeyGen currently lists Video Agent at $0.0333 per output second, which is about $2 per generated minute.
Does HeyGen CLI work on Windows?
Not natively yet. HeyGen documents macOS and Linux binaries and recommends Windows Subsystem for Linux while native Windows support is pending.
Can HeyGen CLI run in CI or an AI-agent workflow?
Yes. It defaults to structured JSON, supports environment-based authentication, returns status and failure data, and can either poll asynchronously or wait for a job.
Where does HeyGen CLI store the API key?
Interactive API-key login stores credentials under ~/.heygen/credentials. In CI, HeyGen supports the HEYGEN_API_KEY environment variable; use a real secret manager and keep the value out of logs and source control.
Bottom line
Our HeyGen CLI verdict
HeyGen CLI is a practical interface for teams that already want HeyGen output and need repeatable, programmatic video production. Its JSON-first design and job controls are much more automation-friendly than driving the web editor. Start with a short, representative batch, measure cost per accepted minute, and require both automated checks and human review before publishing.
Visit HeyGen CLI website ↗Similar Content Creator Tools
View all Content Creator AI tools →
Avatar V
Avatar V - HeyGen's new AI avatar model that generates studio-quality, hyperrealistic videos from a 15-second clip
Ernie Image
ERNIE-Image - Baidu's 8B open-weight text-to-image model that nears top rivals on benchmarks despite its small size
MAI-Image-2
MAI Image 2 - Microsoft AI's image model with upgraded photorealism and creativity
Happy Horse
Happy Horse - Alibaba's new SOTA AI video model
AI training for the future of work.
Get access to all our AI courses, hundreds of real-world AI use cases, live expert-led workshops, an exclusive network of AI early adopters, and more.
AI Courses
Get unlimited access to all of our current & upcoming industry-specific AI courses for the duration of your subscription.
Daily Guides
To keep up with the rapid pace of AI, our team publishes AI implementation guides daily. Our library contains 300+ practical use cases to automate real-world work.
Workshops
Join weekly, live, interactive sessions with industry leaders who are at the forefront of AI for hands-on implementation guidance and exclusive insights.
Community
Network with an exclusive community of AI-first professionals who are working smarter with AI. Learn how early adopters are using AI in their work and businesses.