Overview - HeyGen Documentation

The HeyGen CLI gives developers and AI agents command-line access to HeyGen’s video platform. It wraps the v3 API, outputs structured JSON by default, and works out of the box in scripts, CI pipelines, and agent workflows.

1. Install the CLI

curl -fsSL https://static.heygen.ai/cli/install.sh | bash

This installs the latest stable release into ~/.local/bin. Verify the installation:

heygen --version

The CLI ships as a single binary with no runtime prerequisites. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) are supported. Windows support is coming soon — WSL is recommended in the meantime.

2. Authenticate

heygen auth login

Paste your API key when prompted. The key is stored locally at ~/.heygen/credentials. For CI/Docker/agent environments, set the environment variable instead — it takes precedence over stored credentials:

export HEYGEN_API_KEY=your-api-key

Verify your credentials:

heygen auth status

Log in with OAuth

As an alternative to an API key, log in with your HeyGen account via OAuth:

heygen auth login --oauth

This opens your browser to sign in at HeyGen.com.

Logging in one way replaces the other stored credential. Non-interactive shells (piped input, CI=true, or HEYGEN_NONINTERACTIVE=1) default to the API-key flow — pass --oauth explicitly in automation. Set BROWSER=none or HEYGEN_NO_BROWSER=1 to print the sign-in URL instead of opening a browser.

3. Create a Video

Send a prompt to the Video Agent and let it handle avatar, voice, and layout:

heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"

Output

{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}

The CLI returns immediately with structured JSON. Your video is generating in the background. For full control over every parameter, use video create with a JSON body:

heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our Q4 earnings call.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'

Use --request-schema on any command to discover the expected JSON fields — no auth required:

heygen video create --request-schema
heygen video-agent create --request-schema

4. Check Status

Poll for the result using the video_id returned from step 3:

heygen video get vid_xyz789

Output

{
  "data": {
    "id": "vid_xyz789",
    "title": "Product launch explainer",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.com/thumb/vid_xyz789.jpg",
    "duration": 32.5,
    "created_at": 1711288320,
    "completed_at": 1711288452
  }
}

Status moves through pending → processing → completed or failed. If the video fails, the response includes failure_code and failure_message fields.

Tip: Add --wait to the create command to block until the video is ready instead of polling manually. The default timeout is 20 minutes — override with --timeout 30m. On timeout, the CLI exits with code 4 and prints the last known resource state along with a hint to resume polling manually.

5. Download the Video

Once complete, download to a local file:

heygen video download vid_xyz789 --output-path ./launch-video.mp4

Output

{
  "asset": "video",
  "message": "Downloaded video to ./launch-video.mp4",
  "path": "./launch-video.mp4"
}

If the video was created with captions enabled, you can download the captioned version:

heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4

​1. Install the CLI

​2. Authenticate

​Log in with OAuth

​3. Create a Video

​4. Check Status

​5. Download the Video

1. Install the CLI

2. Authenticate

Log in with OAuth

3. Create a Video

4. Check Status

5. Download the Video