HeyGen

A HeyGen connection reaches https://api.heygen.com, the API behind HeyGen's AI avatar videos. Browsing is the cheap half: avatars, the looks that belong to them, voices, Studio templates, your rendered videos and your remaining credits are all reads an agent can do freely. Rendering is the expensive half, and it is where the gate sits — creating a video or synthesising speech starts switched off and asks a human every time, because both spend credits the moment they are accepted.

What you need

A HeyGen API key. That is a static credential, so this connector works end to end today: you paste the key once and the gateway seals it.

1. Sign in and open Settings → API in the HeyGen app.
2. Copy the key shown there. HeyGen issues one key per account rather than scoped keys, so there is no least-privilege selection to make at this step — the scoping happens in Permaura instead, by leaving the two generating actions switched off.
3. If the key is ever exposed, rotate it from the same screen. Rotation invalidates the old key immediately, so update the connection's credential at the same time.

Paste it exactly as HeyGen gave it to you. Permaura sends it as the X-Api-Key header, so you do not add a prefix of your own.

Add the connection

In the console, open Access → Connections → Add connection and pick HeyGen from the catalog. Paste the API key when the form asks for the credential. It is sealed on your gateway at that moment and never displayed again, and from then on Permaura injects it server-side on each approved call.

Adding the connection makes these actions possible, not permitted. An agent cannot touch any of them until a grant allows it.

What the agent can do

Capabilities are namespaced under the connection id, so an agent sees avatars.list as <connection>.avatars.list.

Action	What it does	On by default
avatars.list	Lists avatar groups, meaning the characters themselves	Yes
avatar_looks.list	Lists the looks within a group; a look id is the avatar_id you render with	Yes
voices.list	Lists voices, filterable by engine, language and gender	Yes
voices.read	Retrieves one voice by voice_id	Yes
videos.list	Lists the videos in your account	Yes
videos.read	Reads one video's render status and, once finished, its URL	Yes
templates.list	Lists the Studio templates in your workspace	Yes
video_translations.list	Lists video translation jobs	Yes
user.read	Reads your account's remaining credits and billing type	Yes
videos.create	Renders an avatar video from a script	No, and it asks for approval
speech.create	Synthesises speech with a Starfish voice, returning an audio URL	No, and it asks for approval
videos.delete	Permanently deletes a video and its files	No, and it asks for approval

An agent that can only read is still useful here: it can find the right avatar and voice, watch a render you started, and tell you what a job cost. Turning videos.create on is the deliberate step that lets it spend.

Good to know

• The host is pinned, and each path carries its own version. HeyGen versions per endpoint rather than per API, so the base URL is the bare host and every capability path starts with its own /v3 segment. Every call goes to api.heygen.com and nowhere else.
• This connector is v3 only, on purpose. HeyGen's older /v1 and /v2 endpoints — POST /v2/video/generate, GET /v1/video_status.get, GET /v1/user/me and the rest — are scheduled for retirement on 1 November 2026. Everything here uses the v3 equivalents, so nothing in it needs migrating before that date.
• Rendering is asynchronous, and polling is the only way to hear back. videos.create returns a video id straight away, not a video. The render then runs in the background and an agent has to poll videos.read until status is completed and video_url is populated. A failed render comes back with failure_code and failure_message on the same object. HeyGen's callback_url webhook is deliberately not forwarded: it would let an agent name any host on the internet and have HeyGen deliver the finished video there, which is exactly what pinning the base URL is meant to prevent.
• The avatar id you need comes from looks, not groups. avatars.list returns characters; avatar_looks.list returns the outfits and poses within them, and it is the look id that goes into videos.create as avatar_id. Passing a group id there will not render.
• For speech, filter voices by engine. speech.create only accepts voices that support HeyGen's Starfish engine, so call voices.list with engine set to starfish first. Unlike a raw audio download, it returns JSON with an audio_url, a duration and optional word timestamps, which comes back through the gateway intact.
• Only the listed inputs reach HeyGen. videos.create forwards type, avatar_id, script, voice_id, title, aspect_ratio and resolution; speech.create forwards text, voice_id, input_type, speed and language. Anything else an agent sends is dropped before the request leaves your gateway. HeyGen's richer options — backgrounds, watermarks, captions, engine selection, multi-scene Studio compositions — are not reachable through this connector, by design.
• An agent cannot feed HeyGen your media. videos.create also supports building a video from an image or from pre-recorded audio, but none of the parameters that carry a file, a URL or an asset id are forwarded, so only the avatar path works here. Rendering from your own footage stays a job for the HeyGen app.
• Scripts are capped. Avatar script text tops out at 5,000 characters, and so does speech.create; speed runs from 0.5x to 2.0x. Output videos run to 30 minutes at most.
• There is no sandbox. HeyGen bills real credits on the first accepted render. user.read is the cheapest way to see what is left before you approve one.
• Concurrency is a hard limit, not a queue. Pay-as-you-go accounts run ten generation jobs at once, counting videos, translations and agent sessions together. Past that, HeyGen returns 429 with a Retry-After header rather than waiting for a slot.
• Lists are cursor-paginated. Every list capability takes limit and an opaque token; the response carries the next_token to send on the following call. There are no page numbers.
• Deleting cannot be undone. videos.delete removes the video and its associated files permanently, which is why it is gated and prompts a human even once enabled.
• The connector card shows a monogram. HeyGen has no Simple Icons entry, so there is no vendor mark to render.