Skip to main content
1

Get your API key

Go to Settings → API in the HeyGen dashboard and generate a key. Save it — you can’t view it again.
export HEYGEN_API_KEY="your-api-key-here"
2

Create a video

Send a prompt to the Video Agent and let it handle the rest:
Request
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": "vid_xyz789",
    "created_at": 1711382400
  }
}
3

Poll for the result

Video generation is async. Use the video_id to check status:
Request
curl -X GET "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.com/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.com/thumb/vid_xyz789.jpg",
    "duration": 32.5
  }
}
Status moves through pendingprocessingcompleted | failed. Once completed, download from video_url.
Skip polling by passing a callback_url in your creation request to get a webhook notification instead.

Resources

Video Agent

Generate videos from a text prompt — the agent handles avatar, script, and production.

Video Translation

Translate videos into 30+ languages with natural voice cloning and lip-sync.

Webhooks

Get notified when videos, translations, and avatars finish processing.

API Limits and Costs

Rate limits, usage, and pricing per operation.

Tools

CLI

Script video creation and translation from your terminal.

MCP Server

Connect HeyGen to AI agents and copilots via Model Context Protocol.

Authentication

API key setup, OAuth tokens, and request signing.