> ## Documentation Index
> Fetch the complete documentation index at: /help/llms.txt
> Use this file to discover all available pages before exploring further.

# HeyGen

> Generate a HeyGen avatar video with the contact's name, wait for it to render, and send it on LinkedIn.

> [!NOTE]
>
> **Pro plan.** HeyGen works through a connection, HTTP steps and listeners (**Wait for webhook**, **Call & wait**), which are part of Pro and Agency (and the free trial). Anything you already have keeps working on every plan. See [Plans and billing](/help/account/billing.md).

A **Call & wait** step sends HeyGen a script with the contact's first name and company, plus this contact's callback URL. HeyGen renders the avatar video and calls back; the next LinkedIn message sends the link.

> [!NOTE]
>
> **How it connects:** HeyGen's API with your key in the `x-api-key` header. See [HeyGen's API docs](https://docs.heygen.com) (create video, video status, callbacks). The request below follows HeyGen's docs; check the callback's fields with **Listen for test event**.

## Before you start

* **HeyGen plan:** the API is billed separately from HeyGen's app plans, per video length (HeyGen's API pricing).
* **An API key:** copy it from HeyGen's API settings.
* **Your avatar and voice ids:** from HeyGen's avatar and voice lists (in the app or through its API).

## 1. Connect HeyGen

In Kerux, open **Integrations > Connections**, click **Connect** on **Custom API** (under **Developers**):

* **How it signs in:** **API key in a header**, **Header name** `x-api-key`, paste the key.
* **Base URL:** `https://api.heygen.com`

Click **Save**, then **Test connection**.

## 2. Create the video and wait

After **Invitation accepted**, add a **Call & wait** step named `heygen`, pick the HeyGen connection. Its request:

```json theme={null}
{
  "method": "POST",
  "url": "/v3/videos",
  "bodyType": "json",
  "body": {
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "voice_id": "YOUR_VOICE_ID",
    "script": "Hi {{contact.first_name}}, I made this for the team at {{contact.company}}...",
    "callback_url": "{{wait.callback_url}}",
    "callback_id": "{{contact.linkedin_url}}"
  }
}
```

Kerux never sends a script with an empty value: give names a default (`{{contact.first_name | default: "there"}}`). Set the wait limit to cover rendering (for example 2 hours).

## 3. Send the link

HeyGen's callback reports the video's status and id. Click **Listen for test event** and run one contact to see it. If the callback has no shareable link, add a **Webhook / HTTP** step that GETs `/v3/videos/{{steps.heygen.payload.<path to the video id>}}` and use the video URL from that answer in your LinkedIn message.

## Test with one contact

In the **Builder**, click **Test** to open **Test on one contact**. The journey shows the request, HeyGen's first answer and the callback.

## Common errors

> [accordion] 401 Unauthorized
>
> The key is wrong. Copy it again from HeyGen and edit the connection.

> [accordion] 400 with an avatar or voice error
>
> The avatar or voice id doesn't exist in your account. Copy the ids again.

> [accordion] Not enough credits
>
> Your HeyGen API balance ran out. The contact stops in **Needs attention**; top up and click **Retry**.

Related: [Webhook steps](/help/integrations/webhook-steps.md), [Tavus](/help/integration-guides/tavus.md), [Vidyard](/help/integration-guides/vidyard.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.