HeyGen API key: get one and make your first video

To get a HeyGen API key, open HeyGen's API dashboard (app.heygen.com/developers/api) and click to generate a key. Send it in an X-Api-Key header to https://api.heygen.com; GET /v3/users/me confirms it works. Then POST /v3/video-agents with a prompt and poll until the video is completed.

The HeyGen facts are quoted from its developer docs: API key, quick start, webhooks, error codes and the version comparison, read on 2026-09-29. What the calls cost is in HeyGen API pricing.

How do I get a HeyGen API key?

HeyGen's API key guide gives these steps:

• Go to the HeyGen API dashboard and click to generate your key.
• Store it in an environment variable, which HeyGen recommends: export HEYGEN_API_KEY="your-api-key-here".
• Never commit the key or expose it in client-side or browser code; call the API from a backend. Rotate it periodically from the API dashboard.
• If you also call Sume's API, its authentication docs give similar advice: keep API keys on trusted servers, CI secret stores, or local developer machines.

How do I test the key and make a first video?

Call GET /v3/users/me with the key. A 200 with your account details confirms it is valid, and the billing_type (wallet, subscription, or usage_based) with its matching field shows your balance and billing model. Keys can be limited with permission scopes; GET /v3/api_keys/self returns the key's scope_mode (full, read_only, or custom), its scopes and its expiration.

For the first video, the quick start sends a prompt to POST /v3/video-agents, which returns a session_id; you poll the session for a video_id, then poll GET /v3/videos/{video_id} until its status is completed or failed. HeyGen Video Agent: API and pricing walks through that call and what it costs.

export HEYGEN_API_KEY="your-api-key-here"

# Is the key valid? Shows billing_type and balance
curl "https://api.heygen.com/v3/users/me" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

# Which scopes does this key hold?
curl "https://api.heygen.com/v3/api_keys/self" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Why does HeyGen say my API key is invalid?

When auth fails, the API returns unauthorized (401). The error page says the key "is invalid, expired, or missing", and to verify you send it in the X-Api-Key header and that it is active. Related statuses:

Can HeyGen notify me instead of polling?

Yes. Register a webhook endpoint with POST /v3/webhooks/endpoints, sending a url (a publicly accessible HTTPS URL) and, optionally, the events you want; omit events to receive all of them.

• The response includes a secret. Store it: it is not shown again, and list responses return null.
• Each delivery has a signature header: a hex-encoded HMAC-SHA256 of the raw request body, computed with that secret. Compute the same digest over the raw body and compare in constant time; refuse the request if your stored secret is empty.
• Rotating the secret invalidates the old one immediately, so expect a brief window of failed verifications.

Should I still use HeyGen's v1 or v2 endpoints?

Not for new work. HeyGen's version comparison says v1/v2 stay fully operational until October 31, 2026, and v3 is "recommended for all new development". HeyGen API v2 deprecation covers the move.