Skip to main content

​
Getting Your API Key

  1. Go to the HeyGen API dashboard.
  2. Click to generate your API key.

​
Configuring Your API Key

​
.env file

If your project uses a .env file (common with Node.js, Python, or frameworks like Next.js):

​
Claude Code

If you’re using Claude Code or any terminal-based workflow, set the key in your shell before starting:
Alternatively, add it to your shell profile (~/.bashrc, ~/.zshrc) so it persists across sessions:

​
HeyGen Skills (in Claude)

When using HeyGen through the Skills integration in Claude’s computer environment, the API key is read from the environment. Make sure HEYGEN_API_KEY is set before the skill executes any API calls.

​
Using the Key in Requests

All HeyGen API requests authenticate via the X-Api-Key header. The base URL for all endpoints is https://api.heygen.com. When auth fails, the API returns unauthorized (401).

​
Quick verification

You can verify your key is working by fetching your account info. Full schema: GET /v3/users/me.
A 200 response with your account details confirms your key is valid. The billing_type and corresponding billing field (wallet, subscription, or usage_based) show your current balance and billing model.

​
Restricting Key Permissions

Use permission scopes to limit a key to only the resources and actions it needs. See API Key Permission Scopes for the complete, automatically updated mapping of scopes to endpoints. To check which scopes a key holds, call GET /v3/api_keys/self with that key. It returns the key’s name, scope_mode (full, read_only, or custom), scopes, and expiration, and works with any key regardless of its scopes.

​
Security Best Practices

  • Never commit your API key to version control. Add .env to your .gitignore.
  • Never expose the key in client-side / browser code. Always call the API from a backend or server environment.
  • Rotate your key periodically via the API dashboard.
  • Monitor usage on the API usage page.