### Install Stripe CLI and Projects Plugin

Source: https://developers.heygen.com/docs/stripe-projects

Install the Stripe CLI and the Projects plugin, then log in and initialize a project. This sets up the necessary tools for provisioning services.

```bash
brew install stripe/stripe-cli/stripe   # Stripe CLI
stripe plugin install projects          # Projects plugin
stripe login                            # authenticate (opens browser)
stripe projects init                    # initialize a project in the current directory
```

--------------------------------

### Install HeyGen CLI and Load API Key

Source: https://developers.heygen.com/docs/stripe-projects

Install the HeyGen CLI and load the API key from the .env file into the shell environment. The CLI uses the HEYGEN_API_KEY environment variable.

```bash
curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # install the HeyGen CLI
set -a && source .env && set +a                             # load the key from .env
export HEYGEN_API_KEY="$HEYGEN_HEYGEN_API_KEY"              # the CLI reads HEYGEN_API_KEY
```

--------------------------------

### Install HeyGen Skills for Agent Hosts

Source: https://developers.heygen.com/docs/for-ai-agents

Install the official 'heygen-com/skills' repo for agent hosts that support installable skills. This ensures a consistent baseline for each new session.

```bash
git clone https://github.com/heygen-com/skills.git ~/.claude/skills/heygen-skills
# or other paths as listed in the table
```

--------------------------------

### Create Video with Direct Video Creation

Source: https://developers.heygen.com/docs/voices/overview

This example demonstrates direct video creation, where you can set the avatar, voice, and script.

```APIDOC
## POST /v3/videos

### Description
Creates a video directly by specifying the video type, avatar, voice ID, and script.

### Method
POST

### Endpoint
/v3/videos

### Request Body
- **type** (string) - Required - The type of video to create (e.g., "avatar").
- **avatar_id** (string) - Required - The ID of the avatar to use.
- **voice_id** (string) - Required - The ID of the voice to be used for narration.
- **script** (string) - Required - The spoken script for the video.
```

--------------------------------

### Create Video with Video Agent

Source: https://developers.heygen.com/docs/voices/overview

This example shows how to create a video using a video agent and specifying a voice_id.

```APIDOC
## POST /v3/video-agents

### Description
Creates a video using a video agent, allowing you to specify a prompt and a voice ID.

### Method
POST

### Endpoint
/v3/video-agents

### Request Body
- **prompt** (string) - Required - The script or prompt for the video.
- **voice_id** (string) - Required - The ID of the voice to be used for narration.
```

--------------------------------

### Install HeyGen CLI

Source: https://developers.heygen.com/docs/for-ai-agents

Installs the HeyGen CLI using a curl script. Supports macOS and Linux. Verify installation with `heygen --version`.

```bash
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
```

--------------------------------

### Install HeyGen Skills

Source: https://developers.heygen.com/docs/for-ai-agents

Install the official heygen-com/skills repository for agent hosts that support installable skills. This provides a runtime contract, mode-detection ladder, and producer pipelines for video, avatar creation, and translation.

```APIDOC
## Install HeyGen Skills

For agent hosts that support installable skills (Claude Code, Codex, Cursor, OpenClaw, Hermes), install the official [`heygen-com/skills`](https://github.com/heygen-com/skills) repo.

Agent-facing install guide: [`INSTALL_FOR_AGENTS.md`](https://github.com/heygen-com/skills/blob/master/INSTALL_FOR_AGENTS.md).

| Agent host  | Default skill install path                                              |
| ----------- | ----------------------------------------------------------------------- |
| Claude Code | `~/.claude/skills/heygen-skills`                                        |
| Codex       | `~/.codex/skills/heygen-skills`                                         |
| Cursor      | `~/.cursor/skills/heygen-skills`                                        |
| OpenClaw    | `~/.openclaw/skills/heygen-skills` (or `clawhub install heygen-skills`) |
| Hermes      | `~/.hermes/skills/heygen-skills`                                        |
```

--------------------------------

### Install requests library

Source: https://developers.heygen.com/docs/bulk-video-translation

Install the Python 'requests' library using pip. This is required for making API calls.

```bash
pip install requests
```

--------------------------------

### List Avatar Groups

Source: https://developers.heygen.com/docs/connecting-your-app-to-heygen-with-oauth-20

This example demonstrates how to make a GET request to list avatar groups using an access token.

```APIDOC
## GET /v3/avatars

### Description
Retrieves a list of avatar groups available in your HeyGen account.

### Method
GET

### Endpoint
https://api.heygen.com/v3/avatars

### Parameters
#### Headers
- **Authorization** (string) - Required - The access token in the format "Bearer YOUR_ACCESS_TOKEN".

### Request Example
```bash
curl -X GET https://api.heygen.com/v3/avatars \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```

--------------------------------

### Completed Video Response Example

Source: https://developers.heygen.com/docs/video-agent

This is an example of a successful response when a video generation is completed. It includes the video URL, duration, and timestamps.

```json
{
  "data": {
    "id": "vid_xyz789",
    "title": "Q3 Product Launch Explainer",
    "status": "completed",
    "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.ai/thumb/vid_xyz789.jpg",
    "duration": 45.2,
    "created_at": 1711382400,
    "completed_at": 1711382680
  }
}
```

--------------------------------

### Use HeyGen CLI for Video Operations

Source: https://developers.heygen.com/docs/stripe-projects

Examples of using the HeyGen CLI to list available avatars, create a video agent, and retrieve video details. Assumes the API key is set in the environment.

```bash
heygen avatar list
heygen video-agent create --prompt "30-second product demo" --wait
heygen video get <video-id>
```

--------------------------------

### Video Translation Response Example

Source: https://developers.heygen.com/docs/video-translation-precision

Example of a successful batch translation response, indicating the video translation IDs for each requested language.

```json
{
  "data": {
    "video_translation_ids": [
      "tr_abc123-en",
      "tr_abc123-es",
      "tr_abc123-fr"
    ]
  }
}
```

--------------------------------

### Create a Photo Avatar

Source: https://developers.heygen.com/docs/create-avatar

This example shows how to create a new avatar from a photo URL. The generated avatar can then be used as a reference for future prompt-based generations.

```APIDOC
## Create a Photo Avatar

### Description
Creates a new avatar from a provided photo URL. This is often the first step to establishing a character's identity for subsequent prompt-based variations.

### Method
POST

### Endpoint
/v3/avatars

### Request Body
- **type** (string) - Required - The type of avatar creation, should be "photo".
- **name** (string) - Required - The name of the avatar.
- **file** (object) - Required - Contains details about the source file.
  - **type** (string) - Required - The type of file source, should be "url".
  - **url** (string) - Required - The URL of the photo to use for avatar creation.

### Request Example
```json
{
  "type": "photo",
  "name": "Sarah",
  "file": { "type": "url", "url": "https://example.com/sarah-headshot.png" }
}
```

### Response
#### Success Response (200)
- **avatar_item.id** (string) - The unique identifier for the created avatar look.
- **avatar_group.id** (string) - The unique identifier for the avatar group.

#### Response Example
(Example response structure not provided in source, but would typically include IDs for the created avatar and its group)
```

--------------------------------

### Create Video Agent Prompt (Node.js)

Source: https://developers.heygen.com/docs/overview

This Node.js example uses the fetch API to send a prompt to the Video Agent API. It requires your HEYGEN_API_KEY to be set in the environment. The output includes the session ID and status.

```javascript
const resp = await fetch("https://api.heygen.com/v3/video-agents", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Create a 30-second product walkthrough for a new project management app",
    }),
  });
  const { data } = await resp.json();
  console.log(data.session_id, data.status);
```

--------------------------------

### Fetch Avatars

Source: https://developers.heygen.com/docs/api-key

This example demonstrates how to fetch a list of available avatars using your API key. All HeyGen API requests authenticate via the `X-Api-Key` header.

```APIDOC
## GET /v3/avatars

### Description
Fetches a list of available avatars.

### Method
GET

### Endpoint
https://api.heygen.com/v3/avatars

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - Your HeyGen API key.

### Request Example
```bash
curl -X GET "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

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

```python
import os, requests

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

--------------------------------

### Quick Verification - Get Current User

Source: https://developers.heygen.com/docs/api-key

Verify your API key is working by fetching your account information. A successful response with `"code": 100` confirms the key is valid.

```APIDOC
## GET /v1/user/me

### Description
Fetches the current authenticated user's account information.

### Method
GET

### Endpoint
https://api.heygen.com/v1/user/me

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - Your HeyGen API key.

### Request Example
```bash
curl -X GET "https://api.heygen.com/v1/user/me" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response
#### Success Response (200)
- **code** (integer) - Response code.
- **data** (object) - User account details.
  - **username** (string) - User's username.
  - **email** (string) - User's email address.
  - **first_name** (string) - User's first name.
  - **last_name** (string) - User's last name.
  - **billing_type** (string) - The user's billing model (e.g., "wallet", "subscription").
  - **wallet** (object) - Details for wallet-based billing.
    - **currency** (string) - The currency of the wallet.
    - **remaining_balance** (number) - The remaining balance in the wallet.
    - **auto_reload** (object) - Auto-reload settings.
      - **enabled** (boolean) - Whether auto-reload is enabled.
- **message** (string) - Null for successful requests.

#### Response Example
```json
{
  "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
}
```
```

--------------------------------

### List Available Voices (Node.js)

Source: https://developers.heygen.com/docs/voices/overview

This Node.js example retrieves and logs the first five voices matching the specified language and gender. It uses the fetch API and requires your API key to be set in the environment.

```javascript
const resp = await fetch(
  "https://api.heygen.com/v3/voices?language=English&gender=female",
  { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY } }
);
const { data } = await resp.json();
data.slice(0, 5).forEach((v) =>
  console.log(`${v.voice_id} — ${v.name} (${v.language})`)
);
```

--------------------------------

### Convert Text to Speech (Node.js)

Source: https://developers.heygen.com/docs/voices/speech

This Node.js example shows how to use the `fetch` API to convert text to speech. It logs the audio URL and duration. Ensure your `HEYGEN_API_KEY` is set in your environment variables.

```javascript
const resp = await fetch("https://api.heygen.com/v3/voices/speech", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Hello from HeyGen!",
      voice_id: "1bd001e7e50f421d891986aad5c8bbd2",
    }),
  });
  const { data } = await resp.json();
  console.log(data.audio_url, data.duration);
```

--------------------------------

### Example CSV for Bulk Translation

Source: https://developers.heygen.com/docs/bulk-video-translation

Prepare a CSV file with translation job details including title, output language, video URL, and an optional folder ID. Ensure the video URL is publicly accessible.

```csv
title,output_language,url,folder_id
"Product Demo","Spanish","https://example.com/demo.mp4","folder_123"
"Onboarding","French","https://example.com/onboard.mp4",""
"Q4 Earnings","Japanese","https://example.com/q4.mp4",""
```

--------------------------------

### Video Agent Session Creation Response

Source: https://developers.heygen.com/docs

Example JSON response after creating a video agent session. It includes the session ID and initial status.

```json
{ "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
```

--------------------------------

### Upload PDF and Generate Video (Python)

Source: https://developers.heygen.com/docs/upload-assets

Upload a PDF file using Python to get an asset ID, then use this ID to generate a video. Requires the 'requests' library and the HEYGEN_API_KEY to be defined.

```python
import requests

# Step 1: Upload
with open("quarterly-report.pdf", "rb") as f:
    upload_resp = requests.post(
        "https://api.heygen.com/v3/assets",
        headers={"X-Api-Key": HEYGEN_API_KEY},
        files={"file": f},
    )
asset_id = upload_resp.json()["data"]["asset_id"]

# Step 2: Generate
gen_resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={
        "prompt": "Summarize the key findings from this quarterly report in a 60-second video",
        "files": [{"type": "asset_id", "asset_id": asset_id}],
    },
)
session = gen_resp.json()["data"]
```

--------------------------------

### Video Translation with Stock Voice

Source: https://developers.heygen.com/docs/video-translate

This example demonstrates how to use the Video Translation API with the 'stock_voice_config' option enabled to utilize a preset stock voice. This is an enterprise feature and requires contacting your HeyGen account team.

```APIDOC
## POST /v3/video-translations

### Description
Translates a video into specified output languages, with an option to use a stock voice.

### Method
POST

### Endpoint
https://api.heygen.com/v3/video-translations

### Parameters
#### Request Body
- **video** (object) - Required - The video to translate. Can be of type 'url' or 'base64'.
  - **type** (string) - Required - Type of video input ('url' or 'base64').
  - **url** (string) - Required if type is 'url' - The URL of the video.
- **output_languages** (string[]) - Required - An array of languages to translate the video into.
- **mode** (string) - Optional - Translation mode (e.g., 'speed').
- **title** (string) - Optional - The title for the translated video.
- **stock_voice_config** (object) - Optional - Configuration for using stock voices.
  - **use_stock_voice** (boolean) - Required if stock_voice_config is present - Set to `true` to use a preset stock voice.
  - **preferred_stock_voice_ids** (string[]) - Optional - An array of stock voice IDs to prioritize.

### Request Example
```json
{
  "video": {
    "type": "url",
    "url": "<video_url>"
  },
  "output_languages": ["Spanish"],
  "mode": "speed",
  "title": "My Translated Video",
  "stock_voice_config": {
    "use_stock_voice": true
  }
}
```

### Response
#### Success Response (200)
- **translation_id** (string) - The ID of the translation job.
- **status** (string) - The current status of the translation.
- **output_url** (string) - The URL of the translated video (if available).

#### Response Example
```json
{
  "translation_id": "trans_12345abcde",
  "status": "processing",
  "output_url": null
}
```
```

--------------------------------

### Poll for Video Generation Status

Source: https://developers.heygen.com/docs/video-agent

This example demonstrates how to poll for video generation status. It first polls the session to get the video ID and then polls the video for its final status and URL.

```APIDOC
## Poll for completion

Video generation is asynchronous. First, poll the session to get the `video_id`, then poll the video for its final status:

* [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) — session status and assigned `video_id`
* [`GET /v3/videos/{video_id}`](/reference/get-video) — final render status and `video_url`

### Request Example (Python)
```python
import time, requests

# Step 1: wait for video_id to be assigned
video_id = None
while not video_id:
    sess = requests.get(
        f"https://api.heygen.com/v3/video-agents/{session_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    video_id = sess.get("video_id")
    if not video_id:
        time.sleep(5)

# Step 2: poll video until complete
while True:
    video = requests.get(
        f"https://api.heygen.com/v3/videos/{video_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    if video["status"] in ("completed", "failed"):
        break
    time.sleep(10)

print(video["video_url"])
```

### Response Example (Completed Video)
```json
{
  "data": {
    "id": "vid_xyz789",
    "title": "Q3 Product Launch Explainer",
    "status": "completed",
    "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.ai/thumb/vid_xyz789.jpg",
    "duration": 45.2,
    "created_at": 1711382400,
    "completed_at": 1711382680
  }
}
```

### Video status transitions

The `status` field progresses through these values:

| Status       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `pending`    | Video creation request accepted, queued for processing.        |
| `processing` | The agent is generating the video.                             |
| `completed`  | Video is ready. `video_url` contains the download link.        |
| `failed`     | Generation failed. Check `failure_code` and `failure_message`. |

### Response fields

| Field                 | Type            | Description                                                        |
| --------------------- | --------------- | ------------------------------------------------------------------ |
| `id`                  | string          | Unique video identifier.                                           |
| `title`               | string \| null  | Video title.                                                       |
| `status`              | string          | Current status: `pending`, `processing`, `completed`, or `failed`. |
| `video_url`           | string \| null  | Presigned download URL. Present when `completed`.                  |
| `thumbnail_url`       | string \| null  | Thumbnail image URL.                                               |
| `gif_url`             | string \| null  | Animated GIF preview URL.                                          |
| `captioned_video_url` | string \| null  | Video with burned-in captions.                                     |
| `subtitle_url`        | string \| null  | SRT subtitle file download URL.                                    |
| `duration`            | number \| null  | Video duration in seconds.                                         |
| `created_at`          | integer \| null  | Unix timestamp of creation.                                        |
| `completed_at`        | integer \| null  | Unix timestamp when generation finished.                           |
| `failure_code`        | string \| null  | Machine-readable failure reason. Only when `failed`.               |
| `failure_message`     | string \| null  | Human-readable failure description. Only when `failed`.            |
| `video_page_url`      | string \| null  | Link to the video in the HeyGen app.                               |
```

--------------------------------

### Create Product Demo with Style and File References

Source: https://developers.heygen.com/docs/styles-and-references

Use this JSON payload to create a product demo. Attach reference images or documents by specifying their URLs in the 'files' array. The agent will apply the specified style to render your content with the attached files.

```json
{
  "prompt": "Create a product demo using the attached screenshots",
  "style_id": "style_retro_crt",
  "files": [
    { "type": "url", "url": "https://example.com/screenshot-1.png" },
    { "type": "url", "url": "https://example.com/screenshot-2.png" }
  ]
}
```

--------------------------------

### Provision HeyGen API Key Interactively

Source: https://developers.heygen.com/docs/stripe-projects

Use the Stripe CLI to interactively add the HeyGen API service to your project. This process guides you through service details, pricing, terms, and billing setup.

```bash
stripe projects add heygen/api
```

--------------------------------

### Upload PDF and Generate Video (Bash)

Source: https://developers.heygen.com/docs/upload-assets

Upload a PDF file to obtain an asset ID, then use this ID to generate a video summarizing the report. Ensure the HEYGEN_API_KEY environment variable is set.

```bash
# Step 1: Upload the PDF
ASSET_ID=$(curl -s -X POST "https://api.heygen.com/v3/assets" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -F "file=@./quarterly-report.pdf" | jq -r '.data.asset_id')

echo "Uploaded asset: $ASSET_ID"

# Step 2: Generate a video using the uploaded PDF
curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"prompt\": \"Summarize the key findings from this quarterly report in a 60-second video\",
      \"files\": [{ \"type\": \"asset_id\", \"asset_id\": \"$ASSET_ID\" }]
    }"
```

--------------------------------

### Create Video Agent Session

Source: https://developers.heygen.com/docs/video-agent

Initiate a video agent session with a prompt, orientation, and optional files. Use the returned session ID to track progress.

```bash
curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone. Include the attached slides as visual context.",
      "orientation": "landscape",
      "files": [
        { "type": "url", "url": "https://example.com/q3-launch-deck.pdf" }
      ]
    }'
```

```python
import requests

resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={
        "prompt": "Create a 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone.",
        "orientation": "landscape",
        "files": [
            {"type": "url", "url": "https://example.com/q3-launch-deck.pdf"}
        ],
    },
)
data = resp.json()["data"]
session_id = data["session_id"]
```

```javascript
const resp = await fetch("https://api.heygen.com/v3/video-agents", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Create a 45-second explainer about our Q3 product launch.",
      orientation: "landscape",
      files: [
        { type: "url", url: "https://example.com/q3-launch-deck.pdf" },
      ],
    }),
  });
  const { data } = await resp.json();
  const sessionId = data.session_id;
```

--------------------------------

### Create Video Agent Session (Python)

Source: https://developers.heygen.com/docs

Use the requests library to send a POST request to create a video generation session. The response contains a session_id to track the video's progress.

```python
import requests

resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={"prompt": "A presenter explaining our product launch in 30 seconds"},
)
session_id = resp.json()["data"]["session_id"]
```

--------------------------------

### Get a Single Avatar Group

Source: https://developers.heygen.com/docs/avatars

Retrieves a specific avatar group by its ID. This endpoint allows you to get details about a character, such as its name, gender, preview images, and associated voices.

```APIDOC
## GET /v3/avatars/{group_id}

### Description
Retrieves a specific avatar group by its ID.

### Method
GET

### Endpoint
/v3/avatars/{group_id}

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The unique identifier for the avatar group.

### Request Example
```bash
curl -X GET "https://api.heygen.com/v3/avatars/group_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the avatar group details.
  - **id** (string) - The unique identifier for the avatar group.
  - **name** (string) - The name of the avatar group.
  - **gender** (string) - The gender of the avatar.
  - **preview_image_url** (string) - URL to the preview image of the avatar.
  - **preview_video_url** (string) - URL to the preview video of the avatar.
  - **looks_count** (integer) - The number of looks available for this avatar group.
  - **default_voice_id** (string) - The default voice ID associated with the avatar.
  - **consent_status** (string) - The consent status for using the avatar.
  - **status** (string) - The status of the avatar group (e.g., 'completed').
  - **created_at** (integer) - Timestamp when the avatar group was created.

#### Response Example
```json
{
  "data": {
    "id": "group_abc123",
    "name": "Monica",
    "gender": "female",
    "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
    "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
    "looks_count": 3,
    "default_voice_id": "voice_xyz789",
    "consent_status": null,
    "status": "completed",
    "created_at": 1711382400
  }
}
```
```

--------------------------------

### Create a session

Source: https://developers.heygen.com/docs/interactive-sessions

Initiates a new interactive session with the Video Agent. Send your initial prompt to begin processing.

```APIDOC
## POST /v3/video-agents

### Description
Creates a new video agent session in chat mode.

### Method
POST

### Endpoint
/v3/video-agents

### Request Body
- **mode** (string) - Required - Set to "chat" for interactive sessions.
- **prompt** (string) - Required - The initial prompt for the agent.
```

--------------------------------

### Create Video Agent with Webhook

Source: https://developers.heygen.com/docs/video-agent

Use this endpoint to create a video agent and receive POST notifications when the video completes or fails. Include a `callback_url` for asynchronous updates and a `callback_id` for correlating requests.

```bash
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a short welcome video for new employees",
    "callback_url": "https://your-server.com/webhooks/heygen",
    "callback_id": "onboarding-video-001"
  }'
```

--------------------------------

### Get User Account Information

Source: https://developers.heygen.com/docs/connecting-your-app-to-heygen-with-oauth-20

Retrieve user account details, including remaining credits and billing information, by making a GET request to the /v3/users/me endpoint. This requires a valid access token.

```bash
curl -X GET https://api.heygen.com/v3/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json
{
  "code": 100,
  "data": {
    "username": "jane_doe",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "billing_type": "subscription",
    "subscription": {
      "plan": "enterprise",
      "credits": {
        "premium_credits": {
          "remaining": 250,
          "resets_at": "2026-05-01T00:00:00Z"
        },
        "add_on_credits": {
          "remaining": 50,
          "resets_at": null
        }
      }
    }
  },
  "message": null
}
```

--------------------------------

### Get Proofread Session Status

Source: https://developers.heygen.com/docs/video-translation-precision

Polls the status of a proofread session using its ID.

```APIDOC
## GET /v3/video-translations/proofreads/{proofread_id}

### Description
Retrieves the current status of a proofread session. This endpoint is used to poll until the session status is `completed`.

### Method
GET

### Endpoint
/v3/video-translations/proofreads/<proofread_id>

### Response
#### Success Response (200)
- **status** (string) - The current status of the proofread session (e.g., `processing`, `completed`).
- **srt_url** (string) - URL to download the SRT file for editing, available when status is `completed`.
```

--------------------------------

### Filter Voices by Gender

Source: https://developers.heygen.com/docs/voices/search-voices

Use the `gender` parameter to filter voices by gender, for example, `male`.

```bash
curl -X GET "https://api.heygen.com/v3/voices?gender=male" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

--------------------------------

### Initialize Upload

Source: https://developers.heygen.com/docs/upload-assets

Initiates the direct upload process by providing file metadata. Returns an asset ID, a presigned upload URL, and necessary upload headers.

```APIDOC
## POST /v3/assets/direct-uploads

### Description
Initializes the direct upload process for large files. Requires the file's name, MIME type, and exact byte size.

### Method
POST

### Endpoint
/v3/assets/direct-uploads

### Request Body
- **filename** (string) - Required - The name of the file to be uploaded.
- **content_type** (string) - Required - The MIME type of the file (e.g., "video/mp4").
- **size_bytes** (integer) - Required - The exact size of the file in bytes.

### Response
#### Success Response (200)
- **data.asset_id** (string) - The unique identifier for the asset upload.
- **data.upload_url** (string) - A presigned URL for uploading the file bytes.
- **data.upload_headers** (object) - Headers required for the upload request.
- **data.expires_in_seconds** (integer) - The time in seconds until the upload URL expires.
```

--------------------------------

### Filter for TTS-Compatible Voices

Source: https://developers.heygen.com/docs/voices/search-voices

To get voices compatible with the `POST /v3/voices/speech` endpoint, filter by the `engine` parameter with the value `starfish`.

```bash
curl -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

--------------------------------

### Create Video with Direct Video Creation

Source: https://developers.heygen.com/docs/voices/overview

Set the `voice_id` along with your avatar and script for direct video creation. This method allows for more granular control over video elements.

```bash
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "your_look_id",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
    "script": "Welcome to our platform. Today I will walk you through the key features."
  }'
```

--------------------------------

### Get Avatar Group by ID

Source: https://developers.heygen.com/docs/avatars

Fetches detailed information about a specific AI avatar group using its unique ID.

```APIDOC
## GET /v3/avatars/{group_id}

### Description
Retrieves detailed information for a specific AI avatar group identified by its `group_id`.

### Method
GET

### Endpoint
/v3/avatars/{group_id}

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The unique identifier of the avatar group to retrieve.

### Request Example
```bash
curl -X GET "https://api.heygen.com/v3/avatars/group_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the specified avatar group.
  - **id** (string) - The unique identifier for the avatar group.
  - **name** (string) - The name of the avatar group.
  - **gender** (string) - The gender associated with the avatar.
  - **preview_image_url** (string) - URL to a preview image of the avatar.
  - **preview_video_url** (string) - URL to a preview video of the avatar.
  - **looks_count** (integer) - The number of different looks available for this avatar group.
  - **default_voice_id** (string) - The ID of the default voice for this avatar.
  - **consent_status** (string) - The consent status for using the avatar (can be null).
  - **status** (string) - The status of the avatar group (e.g., 'completed').
  - **created_at** (integer) - Timestamp indicating when the avatar group was created.

#### Response Example
```json
{
  "data": {
    "id": "group_abc123",
    "name": "Monica",
    "gender": "female",
    "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
    "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
    "looks_count": 3,
    "default_voice_id": "voice_xyz789",
    "consent_status": null,
    "status": "completed",
    "created_at": 1711382400
  }
}
```
```

--------------------------------

### Get Video Agent Session Status

Source: https://developers.heygen.com/docs

Poll the session to check its status and retrieve the video ID once it's assigned.

```APIDOC
## GET /v3/video-agents/{session_id}

### Description
Retrieves the status and details of a video agent session.

### Method
GET

### Endpoint
https://api.heygen.com/v3/video-agents/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the video agent session.

### Response
#### Success Response (200)
- **data** (object) - Contains session details.
  - **video_id** (string | null) - The ID of the video, if available.

### Response Example
```json
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789"
  }
}
```
```

--------------------------------

### Create an Interactive Video Agent Session (Python)

Source: https://developers.heygen.com/docs/interactive-sessions

This Python script demonstrates how to initiate a video agent session for interactive chat. It sends a POST request with the necessary headers and JSON payload, then extracts the session ID from the response.

```python
import requests

resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={
        "prompt": "Create a 2-minute onboarding video for new engineering hires.",
        "mode": "chat",
        "orientation": "landscape",
    },
)
session = resp.json()["data"]
session_id = session["session_id"]

```

--------------------------------

### Get a Single Look

Source: https://developers.heygen.com/docs/avatar-looks

Retrieves the details of a specific avatar look by its ID. This is useful for fetching information about pre-defined or created avatars.

```APIDOC
## GET /v3/avatars/looks/{look_id}

### Description
Retrieves the details of a specific avatar look.

### Method
GET

### Endpoint
/v3/avatars/looks/{look_id}

### Parameters
#### Path Parameters
- **look_id** (string) - Required - The unique identifier of the look to retrieve.

### Request Example
```bash
curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the avatar look details.
  - **id** (string) - The unique identifier of the look.
  - **name** (string) - The name of the avatar look.
  - **avatar_type** (string) - The type of avatar (e.g., `studio_avatar`, `digital_twin`, `photo_avatar`).
  - **group_id** (string) - The identifier for the group the avatar belongs to.
  - **gender** (string) - The gender of the avatar.
  - **preview_image_url** (string) - URL to a preview image of the avatar.
  - **preview_video_url** (string) - URL to a preview video of the avatar.
  - **default_voice_id** (string) - The default voice ID associated with the avatar.
  - **tags** (array) - An array of tags associated with the avatar look.
  - **supported_api_engines** (array) - An array of supported API engines for this avatar.
  - **status** (string) - The status of the avatar look (e.g., `completed`).

### Response Example
```json
{
  "data": {
    "id": "look_def456",
    "name": "Monica - Business Casual",
    "avatar_type": "photo_avatar",
    "group_id": "group_abc123",
    "gender": "female",
    "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
    "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
    "default_voice_id": "voice_xyz789",
    "tags": ["business", "casual", "female"],
    "supported_api_engines": ["avatar_4_quality", "avatar_4_turbo"],
    "status": "completed"
  }
}
```
```

--------------------------------

### Get Video Details

Source: https://developers.heygen.com/docs

Poll the video using its ID to check its status and retrieve the final video URL upon completion.

```APIDOC
## GET /v3/videos/{video_id}

### Description
Retrieves the details of a generated video, including its status and URL.

### Method
GET

### Endpoint
https://api.heygen.com/v3/videos/{video_id}

### Parameters
#### Path Parameters
- **video_id** (string) - Required - The ID of the video.

### Response
#### Success Response (200)
- **data** (object) - Contains video details.
  - **id** (string) - The ID of the video.
  - **status** (string) - The status of the video (e.g., "completed", "failed").
  - **video_url** (string) - The URL of the generated video.
  - **duration** (number) - The duration of the video in seconds.

### Response Example
```json
{
  "data": {
    "id": "vid_xyz789",
    "status": "completed",
    "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
    "duration": 32.5
  }
}
```
```

--------------------------------

### Generate video and retrieve

Source: https://developers.heygen.com/docs/interactive-sessions

Once the storyboard is approved or `auto_proceed: true` is sent, the session moves to 'generating' and then 'completed'. Fetch the final video using its ID.

```APIDOC
## GET /v3/videos/{video_id}

### Description
Retrieves the final generated video.

### Method
GET

### Endpoint
/v3/videos/{video_id}

### Parameters
#### Path Parameters
- **video_id** (string) - Required - The unique identifier for the video.
```

--------------------------------

### Completed Video Response

Source: https://developers.heygen.com/docs

Example JSON response when a video generation is completed. It includes the video ID, status, and the final video URL.

```json
{ "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }
```

--------------------------------

### List Available Voices

Source: https://developers.heygen.com/docs/voices/overview

Use GET /v3/voices to list available voices with cursor-based pagination. You can filter by language, gender, type, or engine.

```APIDOC
## GET /v3/voices

### Description
Lists available voices with cursor-based pagination. Allows filtering by language, gender, type, or engine.

### Method
GET

### Endpoint
/v3/voices

### Query Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by voice type (`"public"` for the shared library or `"private"` for your cloned voices). Defaults to `"public"`.
- **engine** (string) - Optional - Filter by voice engine (e.g. `"starfish"`). Only voices compatible with that engine are returned.
- **language** (string) - Optional - Filter by language name (e.g. `"English"`, `"Spanish"`, `"Japanese"`).
- **gender** (string) - Optional - Filter by `"male"` or `"female"`.
- **limit** (integer) - Optional - Results per page (1–100). Defaults to `20`.
- **token** (string) - Optional - Opaque cursor token for the next page.

### Response
#### Success Response (200)
- **data** (array) - An array of voice objects.
  - **voice_id** (string) - The unique identifier for the voice.
  - **name** (string) - The name of the voice.
  - **language** (string) - The language the voice speaks.
  - **gender** (string) - The gender of the voice (`"male"` or `"female"`).
  - **preview_audio_url** (string) - URL to a preview audio file of the voice.
  - **support_pause** (boolean) - Indicates if the voice supports pauses.
  - **support_locale** (boolean) - Indicates if the voice supports locale settings.
  - **type** (string) - The type of voice (`"public"` or `"private"`).
- **has_more** (boolean) - Indicates if there are more results available.
- **next_token** (string) - Opaque cursor token for the next page of results.

#### Response Example
```json
{
  "data": [
    {
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "name": "Sara",
      "language": "English",
      "gender": "female",
      "preview_audio_url": "https://files.heygen.ai/voice/preview/sara.mp3",
      "support_pause": true,
      "support_locale": true,
      "type": "public"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
}
```
```

--------------------------------

### Generate Video using HeyGen CLI

Source: https://developers.heygen.com/docs/for-ai-agents

Use the HeyGen CLI to create a video from a prompt. JSON output is the default. Refer to the Output Modes documentation for more options.

```bash
heygen video-agent create --prompt "<prompt>"
```

--------------------------------

### Get a Single Avatar Look

Source: https://developers.heygen.com/docs/avatar-looks

Use this endpoint to retrieve details for a specific avatar look. Ensure your API key is set as an environment variable.

```bash
curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
```

```json
{
  "data": {
    "id": "look_def456",
    "name": "Monica - Business Casual",
    "avatar_type": "photo_avatar",
    "group_id": "group_abc123",
    "gender": "female",
    "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
    "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
    "default_voice_id": "voice_xyz789",
    "tags": ["business", "casual", "female"],
    "supported_api_engines": ["avatar_4_quality", "avatar_4_turbo"],
    "status": "completed"
  }
}
```