Skip to main content

Get your API key

Create a key in Settings → API. 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>

​
Your first video

Authenticate

Create a key in Settings → API. For OAuth and rotation, see the API Key guide.
export HEYGEN_API_KEY="your-api-key-here"

Create a video

Send a prompt to the Video Agent — it scripts, picks the avatar and voice, and renders.
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"}'
Response
{ "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
Watch it build live at https://app.heygen.com/video-agent/{session_id}.

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.
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"])
Response (completed)
{ "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }

​
Pick your endpoint

Video Agent

Prompt → finished video. Flagship.

Avatar V

Pick the avatar, voice, and script yourself.

Cinematic Avatar

Prompt-driven cinematic shots from avatar looks.

Video Translation

30+ languages with voice cloning and lip-sync.

Text to Speech

Text → natural speech audio.

HyperFrames

HTML/CSS/JS → motion-graphics video. New.

​
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

Limits & Pricing

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

​
Troubleshooting

Inspect failure_code and failure_message on GET /v3/videos/{video_id}. Full catalog in Error Codes.
Confirm the X-Api-Key header is set and the key is active in Settings → API.
Rate or concurrency limit hit. Respect Retry-After and back off. See Usage Limits.
A URL you passed couldn’t be fetched — it must be publicly accessible and point directly at the file.