Skip to main content
Generate AI video from a single API call: avatars, voices, translation, motion graphics, and more. Everything below runs on the v3 API.

Get API key

API Playground

CLI

MCP Server

Base URL https://api.heygen.com · Auth header X-Api-Key: <your-key> · What you’ll build: an MP4 from one text prompt.

​
Your first video

Authenticate

Create a key in Settings → API and export it. See the API Key guide for OAuth and rotation.
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. Returns a session_id. Full schema: POST /v3/video-agents.
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

Generation is async. Poll the session for the video_id, then poll the video for its video_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 } }
Skip polling in production. Pass a callback_url in your create request to get a webhook when the video is ready.

​
Pick your endpoint

The Video Agent is the fastest path, but you can also drive each model directly.

Video Agent

Prompt → finished video. The agent handles script, avatar, and scenes. Flagship.

Avatar V

Direct control: pick the avatar, voice, and script. engine: { "type": "avatar_v" }.

Cinematic Avatar

Prompt-driven cinematic shots from 1–3 avatar looks. No script or voice.

Video Translation

Translate any video into 30+ languages with voice cloning and lip-sync.

Text to Speech

Turn text into natural speech audio. Browse or design a voice.

HyperFrames

Render HTML/CSS/JS compositions into motion-graphics video. New.

​
Build with your stack

Webhooks

Get notified when renders finish — no polling.

Authentication

API keys, OAuth 2.0, and request signing.

CLI

Create and translate video from your terminal.

Limits & Pricing

Rate limits, usage, and per-operation cost.
Migrating from v1/v2? Those endpoints are supported until October 31, 2026, but all new capabilities ship on v3. See the version comparison.

​
Troubleshooting

Inspect failure_code and failure_message on GET /v3/videos/{video_id}. The full catalog is in Error Codes.
Your key is missing or invalid. Confirm the X-Api-Key header is set and the key is active in Settings → API. See Authentication.
You’ve hit a rate or concurrency limit. Respect the Retry-After header and back off exponentially. See Usage Limits.
A URL you passed (video, image, audio) couldn’t be fetched. Make sure it’s publicly accessible and points directly at the file. See Error Codes.

All error codes

Machine-readable codes, HTTP statuses, and how to handle each one.