API Integration Advanced

The HeyGen API lets you programmatically generate avatar videos, enabling automation at scale. This lesson covers API authentication, the video creation workflow, polling and webhooks for status updates, and building automated video pipelines.

Authentication

All API requests require an API key passed in the X-Api-Key header. Generate your key from the HeyGen dashboard under Settings → API. Keep your key secure and never expose it in client-side code.

Video Creation Workflow

1. List available avatars

   GET /v2/avatars — retrieve your stock and custom avatars with their IDs.

2. Create a video

   POST /v2/video/generate — specify avatar ID, voice ID, script text, background, and dimensions.

3. Check status

   GET /v1/video_status.get?video_id=xxx — poll until status is "completed" or use webhooks.

4. Download

   The completed response includes a video_url for downloading the finished MP4.

import requests

API_KEY = "your_api_key_here"
headers = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

payload = {
    "video_inputs": [{
        "character": {"type": "avatar", "avatar_id": "your_avatar_id"},
        "voice": {"type": "text", "input_text": "Hello from HeyGen API!",
                  "voice_id": "your_voice_id"}
    }],
    "dimension": {"width": 1920, "height": 1080}
}

resp = requests.post("https://api.heygen.com/v2/video/generate",
                     json=payload, headers=headers)
video_id = resp.json()["data"]["video_id"]

Webhooks

Instead of polling, configure a webhook URL in your HeyGen settings. HeyGen will POST a notification to your endpoint when a video completes rendering, including the video URL and metadata.