Quick Start

Generate your first AI video with the HeyGen API in minutes: authenticate, send one request, and get back an MP4.

What you can build

Create Your Avatar

A digital twin from video, or an avatar from one photo.

Video Agent

Prompt to finished video. Edit single scenes after.

HeyGen Video

Text, image, or reference to a 5–15s clip, up to 2K. New.

Avatar Video

Your avatar, voice, and script, up to Avatar V.

HeyGen Image

Your identity, a new look. Portraits from reference photos.

Templates

Turn any video into a template, then one call per viewer. New.

Look Packs

Dress an avatar in a curated set of looks.

HyperFrames

HTML, CSS, and JS to motion-graphics video.

Instant Voice Clone

One recording to a HeyGen Voice in seconds. New.

Professional Voice Clone

Studio-grade voice trained on 20+ minutes of audio.

Text to Speech

Completed or streaming speech from your HeyGen Voice. New.

Video Translation

175+ languages with voice cloning and lip-sync.

Start with your agent

Paste this into Claude Code, Codex, or Cursor. It reads the whole API, sets up your key, and makes your first video with you.

Prompt for your agent

I want to build with the HeyGen API. Run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/llms.txt (index of every guide and endpoint)
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Ask me what I want to make, and pick the right endpoint from the docs (Video Agent, HeyGen Video, avatar video, HeyGen Image, templates, voice cloning, text to speech, or translation).
3. Make the first call, poll until it finishes, and give me the result URL.

Your first video

Get your API key

Create a key in the API dashboard. Every request below needs it.

Try it in the Playground

Fire a real request from your browser before writing any code.

Base URL https://api.heygen.com · Auth header X-Api-Key: <your-key>

1. Authenticate

   Create a key in the API keys page. For key rotation, see the API Key guide.

   export HEYGEN_API_KEY="your-api-key-here"
   
2. Create a video

   Send a prompt to the Video Agent. It scripts, picks the avatar and voice, and renders.

   curl

   curl -X POST "https://api.heygen.com/v3/video-agents" \
     -H "X-Api-Key: $HEYGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A presenter explaining our product launch in 30 seconds"}'
   

   Python

   import requests
   
   resp = requests.post(
       "https://api.heygen.com/v3/video-agents",
       headers={"X-Api-Key": HEYGEN_API_KEY},
       json={"prompt": "A presenter explaining our product launch in 30 seconds"},
   )
   session_id = resp.json()["data"]["session_id"]
   

   Node.js

   const resp = await fetch("https://api.heygen.com/v3/video-agents", {
     method: "POST",
     headers: {
       "X-Api-Key": process.env.HEYGEN_API_KEY,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       prompt: "A presenter explaining our product launch in 30 seconds",
     }),
   });
   const { session_id } = (await resp.json()).data;
   

   Response

   { "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
   

   Watch it build live at https://app.heygen.com/video-agent/{session_id}.

3. Get the result

   Poll the session for a video_id, then the video for its video_url. Or skip polling with a webhook via callback_url.

   Python

   import time
   
   # 1. Wait for the video_id to be assigned
   video_id = None
   while not video_id:
       sess = requests.get(
           f"https://api.heygen.com/v3/video-agents/{session_id}",
           headers={"X-Api-Key": HEYGEN_API_KEY},
       ).json()["data"]
       video_id = sess.get("video_id")
       if not video_id:
           time.sleep(5)
   
   # 2. Poll the video until it's done
   while True:
       video = requests.get(
           f"https://api.heygen.com/v3/videos/{video_id}",
           headers={"X-Api-Key": HEYGEN_API_KEY},
       ).json()["data"]
       if video["status"] in ("completed", "failed"):
           break
       time.sleep(10)
   
   print(video["video_url"])
   

   curl

   # 1. Session → video_id
   curl "https://api.heygen.com/v3/video-agents/sess_abc123" \
     -H "X-Api-Key: $HEYGEN_API_KEY"
   
   # 2. video_id → video_url
   curl "https://api.heygen.com/v3/videos/vid_xyz789" \
     -H "X-Api-Key: $HEYGEN_API_KEY"
   

   Response (completed)

   { "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }
   

Working from an agent or terminal?

Skip the raw HTTP. Both surfaces wrap the same API.

MCP Server

Plug HeyGen into Claude, Cursor, or any MCP-capable agent. It handles the calls for you.

CLI

heygen video create, heygen video download. Scriptable from any shell or CI job.

Build with your stack

Webhooks

Authentication

Usage Limits

Migrating from v1/v2? Supported until October 31, 2026. See the version comparison.

Troubleshooting

Video status is failed

Inspect failure_code and failure_message on GET /v3/videos/{video_id}. Full catalog in Error Codes.

401 Unauthorized

Confirm the X-Api-Key header is set and the key is active in the API keys page.

429 Too Many Requests

Rate or concurrency limit hit. Respect Retry-After and back off. Enterprise plans get higher limits; see Usage Limits.

400 download_failed

A URL you passed couldn’t be fetched. It must be publicly accessible and point directly at the file.