canonical: https://jentic.com/apis/heygen.com/heygen

# HeyGen API

The HeyGen API generates AI-powered videos featuring lifelike avatars, talking photos, and translated voiceovers. Across 11 endpoints, agents can list available avatars and voices, create photo or digital-twin avatars, generate videos from text prompts and templates, translate existing videos into other languages, and check the status of generation jobs. Authentication uses an X-API-Key header issued from the HeyGen dashboard.

## For AI agents

Generate AI avatar videos, talking-photo clips, and translated videos by submitting text and template inputs to HeyGen, then poll for the rendered output URL.

## Scope

Does not handle live video streaming, video conferencing, or generic image generation - use for AI avatar video, talking-photo, and video translation jobs only.

## Capabilities

- Generate AI avatar videos from a script and a chosen avatar via POST `/v1/video/generate`
- Create a digital twin or photo avatar from a source image using `/v1/avatar/photo` and `/v1/avatar/digital-twin`
- Translate an existing video into another language while preserving the speaker's voice via POST `/v1/video_translate/translate`
- List available avatars and voices to let users pick a presenter and language combination
- Render videos from saved templates with POST `/v1/video_agent/generate` for repeatable branded content
- Poll a video's status with GET `/v1/video/{video_id}` until the rendered URL is ready
- Generate talking-photo clips from a still image and a text script using `/v1/talking_photo`

## Use cases

### Personalised Video Outreach

Sales and marketing teams generate one-to-one prospecting videos by passing a personalised script and a chosen avatar to POST `/v1/video/generate.` The job returns a video_id, then GET `/v1/video/{video_id}` polls until the MP4 URL is ready - typically within a few minutes for short clips. This produces avatar videos at thousands of permutations without recording each one manually.

Example prompt: Call POST `/v1/video/generate` with avatar_id, script 'Hi Alex, here is a quick demo for you', and voice_id, then poll GET `/v1/video/{video_id}` every 30 seconds until status is completed.

### Multilingual Content Localisation

Content teams send an existing English video URL to POST `/v1/video_translate/translate` with a target language; HeyGen produces a translated version with the original speaker's voice cloned into the new language. This drops localisation time from days of voiceover work to minutes per language.

Example prompt: Submit POST `/v1/video_translate/translate` with video_url and output_language=es-ES, then poll the returned job until the translated MP4 URL is ready.

### Template-Driven Video Production

Brand teams set up a HeyGen template with placeholders for name, product, and call-to-action, then generate hundreds of videos via POST `/v1/video_agent/generate` by passing variable values per recipient. The API renders consistent on-brand output without designers re-cutting each clip.

Example prompt: Call POST `/v1/video_agent/generate` with template_id and variables {name: 'Alex', product: 'Pilot'}, then capture the returned video_id for status polling.

### AI Agent Video Workflow

Through Jentic, an AI agent can search 'generate an avatar video' and receive HeyGen's create-and-poll pattern with the input schema. Jentic holds the X-API-Key in the vault, so the agent can drive end-to-end video production - script generation in an LLM, render in HeyGen, post to a CMS - without ever seeing the API key.

Example prompt: Search Jentic for 'generate an avatar video', load the schema for POST `/v1/video/generate`, and execute with avatar_id, voice_id, and a 100-word script.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/video/generate` | Generate an AI avatar video from a script |
| GET | `/v1/video/{video_id}` | Get the status and URL of a generated video |
| POST | `/v1/video_translate/translate` | Translate an existing video into another language |
| POST | `/v1/avatar/photo` | Create a photo avatar from an image |
| POST | `/v1/avatar/digital-twin` | Create a digital twin avatar |
| GET | `/v2/avatars` | List available avatars |
| GET | `/v2/voices` | List available voices |

## Key resources

- **Videos** — Create avatar videos, talking-photo clips, and translated videos, and poll their render status
- **Avatars** — List avatars or create photo and digital-twin avatars from source images
- **Voices** — List available voices across languages and accents
- **Templates** — Render videos from saved templates with placeholder variables
- **Video Translate** — Translate an existing video into another language with voice cloning

## Why Jentic

- **Setup:** Wiring the HeyGen API by hand means adding your API-key request header on every call, spanning both its v1 and v2 endpoints, and polling video status yourself while avatar and translation jobs render. Through Jentic you install once, import the HeyGen API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** HeyGen generation jobs take their inputs in the request body while status reads use the video id in the path (`/v1/video/{video_id}`), so limit the agent to the operations it needs, such as reading a video's status or listing avatars. You choose the operations it may call, so generating a video or a digital twin is only included if you add it.
- **Credential handling:** Your HeyGen API key is stored once, encrypted, by your own Jentic One instance and injected as the API-key request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate an avatar video' or 'translate a video into Spanish', and Jentic returns the matching HeyGen operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Synthesia API** — Synthesia generates AI avatar videos with a comparable feature set focused on enterprise training content
- **Tavus API** — Tavus focuses on personalised video at scale with a similar generate-and-poll workflow
- **ElevenLabs API** — ElevenLabs provides standalone voice cloning that can be paired with HeyGen avatars for custom voiceover

## FAQ

### What authentication does the HeyGen API use?

HeyGen uses an API key passed in the X-API-Key header. Generate the key from the HeyGen dashboard. Through Jentic, the key sits in the encrypted vault and is injected per call so the agent never holds it in context.

### Can I generate a translated video with the original speaker's voice via the HeyGen API?

Yes. POST `/v1/video_translate/translate` accepts a video URL and a target language and returns a job that produces a translated MP4 with the original speaker's voice cloned into the new language. Poll the returned job id until the output URL is available.

### How do I poll for video render completion through Jentic?

Run pip install jentic, search for 'check video render status', and execute against GET `/v1/video/{video_id}.` The response includes status (pending, processing, completed, failed) and, when completed, the video_url for download.

### What rate limits apply to the HeyGen API?

Rate limits depend on the HeyGen plan tier (free, creator, team, enterprise) and are not exposed in the spec; the API returns HTTP 429 when exceeded. Implement exponential backoff and prefer template-based generation for bulk runs to reduce per-render overhead.

### Can I create a custom avatar from a single photo?

Yes. POST `/v1/avatar/photo` creates a photo avatar from an uploaded image, while POST `/v1/avatar/digital-twin` produces a higher-fidelity digital twin from one or more images. Once created, the avatar id can be passed to `/v1/video/generate.`

### Can I limit what my agent is allowed to do with the HeyGen API?

Yes. Jentic One is self-hosted by you, so your own rules decide which HeyGen operations and credentials the agent may use. You can scope it to read-only calls such as checking a video's status with GET `/v1/video/{video_id}` or listing avatars with GET `/v2/avatars`, while withholding generation operations like POST `/v1/video/generate` or POST `/v1/avatar/digital-twin.` Each operation is only available to the agent if you add it, and your stored API key is injected at call time rather than exposed to the agent.