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

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

​
.env file

If your project uses a .env file (common with Node.js, Python, or frameworks like Next.js): 
HEYGEN_API_KEY=your-api-key-here

​
Claude Code

If you’re using Claude Code or any terminal-based workflow, set the key in your shell before starting: 
export HEYGEN_API_KEY="your-api-key-here"
claude  # or whatever command starts your session
Alternatively, add it to your shell profile (~/.bashrc, ~/.zshrc) so it persists across sessions: 
echo 'export HEYGEN_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

​
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. For OAuth-based authentication, see Connecting your app to HeyGen with OAuth 2.0. When auth fails, the API returns unauthorized (401). 
curl -X GET "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

const response = await fetch("https://api.heygen.com/v3/avatars", {
  headers: { "X-Api-Key": process.env.HEYGEN_API_KEY },
});

import os, requests

response = requests.get(
    "https://api.heygen.com/v3/avatars",
    headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"]}
)

​
Quick verification

You can verify your key is working by fetching your account info. Full schema: GET /v3/users/me. 
curl -X GET "https://api.heygen.com/v1/user/me" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

{
  "code": 100,
  "data": {
    "username": "jane_doe",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "billing_type": "wallet",
    "wallet": {
      "currency": "usd",
      "remaining_balance": 42.50,
      "auto_reload": { "enabled": false }
    }
  },
  "message": null
}
A successful response with "code": 100 confirms your key is valid. The billing_type and corresponding billing field (wallet, subscription, or usage_based) show your current balance and billing model.

​
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 in your API dashboard