HeyGen integration

Overview

HeyGen generates AI video – avatar narrations, talking-photo animations, template renders, and full-video translation. The Automize connector covers video generation (async), template flows, translation, asset listings (avatars, voices, templates), and quota inspection.

• Regions: Single global API at api.heygen.com. Generated videos are stored on HeyGen's CDN for 30 days by default; download and re-host if you need persistence.
• Plans: Free has a small monthly minute quota and watermarks all output. Creator removes the watermark. API-tier (Team/Enterprise) unlocks higher concurrency, brand voices, and templates.

Setting up the connection

Auth type: API Key.

1. In HeyGen → Settings → API → Create API Key. Free-tier accounts may not see this option – upgrade to enable API access.
2. Copy and paste the key as the API key. Connector sends X-Api-Key on every call.
3. Run Get Remaining Quota right after pasting – confirms the key has API access and shows your credit balance.

Find your credentials at https://app.heygen.com/settings/api.

Rate limits

Concurrent video generation caps at 3 (Creator), 10 (Team), 50+ (Enterprise). Quota is measured in seconds of rendered video plus per-call credits. Generation is async – submitting more than your concurrency cap queues; it doesn't 429.

Data model

HeyGen's render graph:

    Video         async render job (video_id)
      ├─ inputs   list of clips, each with avatar + voice + script
      ├─ status   processing → completed (or failed)
      └─ output   video_url (CDN, signed 30-day URL)

    Template      reusable named layout with typed variable slots
      └─ variables: text / image_url / video_url / character

    Avatar        Studio (high-fidelity, trained) or Instant
                  (1-min source video). Grouped into Avatar Groups
                  that share a likeness across poses/outfits.

    Voice         Voice ID (pre-built or cloned via Brand Voices)
                  + Locale (en-US, fr-FR, ...).

    Translation   async job (video_translate_id) – source video →
                  target language, audio + (optional) lip-sync.

Two ID prefixes you'll see most:

    v2 video_id            UUID, returned by Generate Video
    video_translate_id     UUID, returned by Translate Video

All long-running operations are async – submit, poll status,
download. There is no synchronous render path.

Available operations

16 operations available. Click any row to jump to its detail.

Operations

Delete Video

Delete a generated video

No input parameters.

Tips

• DELETE /v1/video/{video_id} – removes the rendered output AND the job record. Quota credit isn't refunded.
• Use for output you've already downloaded + stored elsewhere; keeps the dashboard list manageable.

Generate From Template

Generate a video by filling a template's variables

Tips

• POST /v2/template/{template_id}/generate – pass variables matching the template's named slots (text, image_url, video_url).
• Get Template returns the variable list and types. Sending the wrong type silently substitutes a default.

Generate Video

Generate a video from avatar + voice + script

Tips

• POST /v2/video/generate – body is video_inputs[] with avatar + voice + script + (optional) background. Returns video_id; poll Get Video Status.
• voice.voice_id comes from List Voices. avatar.avatar_id comes from List Avatars. Mismatched IDs return generic 400s – verify with the list calls.
• test=true generates a watermarked preview without consuming credits.

Get Remaining Quota

Get the remaining API credit on the account

No input parameters.

Tips

• Returns remaining_quota in seconds of video (not credits). Check before kicking off a batch to avoid mid-run failures.

Get Template

Get a template's variables and structure

Tips

• GET /v2/template/{template_id} – returns the variable schema: each named slot's type (text|image|video|character) and default value.
• Use before Generate From Template to know what variables to pass – passing wrong types silently substitutes the default.

Get Translation Status

Get the status of a translation job

Tips

• Poll until status='success' (translated URL ready) or 'failed'. Typical processing time: 2-5x source video length.
• Failed translations expose error.code – common: unsupported_source_language, audio_track_not_detected, lipsync_alignment_failed.

Get Video Status

Get the status and download URL of a generated video

No input parameters.

Tips

• Poll every 10-30s. status flips through processing → completed (with video_url). Failed videos return error.code; common: invalid_voice_avatar_match, script_too_long, asset_not_ready.

List Avatar Groups

List Instant Avatar groups (your custom avatars)

No input parameters.

Tips

• Avatar Groups bundle pose/outfit variants of the same person. For Talking Photo, use the group_id (which is also the talking_photo_id).

List Avatars

List available avatars (public + your library)

No input parameters.

Tips

• Returns pre-built + custom avatars accessible to your workspace.
• Filter by 'is_public' to separate stock avatars from your trained ones.
• Each avatar has multiple pose/outfit variants – the avatar_id you want is the specific look, not the parent group.

List Brand Voices

List brand voices on the account

No input parameters.

Tips

• Custom cloned voices. Each has a voice_id usable in Generate Video alongside pre-built voices.
• Brand voice cloning requires API-tier (Team/Enterprise) – Free + Creator workspaces won't have any.

List Templates

List your video templates

No input parameters.

Tips

• Returns workspace templates with their template_ids. Includes scenes count + a thumbnail URL.

List Videos

List recently generated videos

No input parameters.

Tips

• Paginated list of historical render jobs. limit (max 100) + token-based pagination.
• Filter by status (processing|completed|failed) – useful for reconciliation reports.

List Voice Locales

List supported locales for voices

No input parameters.

Tips

• Enumerates supported locale codes (en-US, en-GB, fr-FR, es-ES, ...). Pair with a specific voice_id to render in that locale.

List Voices

List available voices (TTS)

No input parameters.

Tips

• Returns Voice IDs across all locales. Filter client-side by language='en' for an English-only list.
• support_pause / support_locale tell you which advanced features each voice supports.

Generate Talking Photo

Animate a still photo with audio/script (Photo Avatar)

Tips

• POST /v2/talking_photo – single still image + script/audio → animated video. talking_photo_id is the uploaded image's ID from List Avatar Groups.

Translate Video

Translate a video into another language

Tips

• POST /v2/video_translate – source URL + target language; returns video_translate_id. Poll Get Translation Status.
• translate_audio_only=true keeps original video, swaps audio + lip-sync. translate_audio_only=false (default) re-renders the talking head.

FAQ

Why is my video stuck in processing?

Most renders complete in 1-5 min. 'Stuck' past 10 min usually means a queue backlog (Free/Creator share a slower pool) or a failed-but-not-marked job – re-poll and check status; if still processing past 20 min, contact support with the video_id.

Can I bring my own avatar?

Yes – Instant Avatar (1-min source video) or Studio Avatar (longer training, higher fidelity). Both register an avatar_id you reference in Generate Video. List Avatars filters by 'custom' to find yours.

What's the cost model?

Per-second of rendered video, with multipliers for studio avatars (>1x) and translation (~2x). Templates cost the same as their underlying render. test=true is free.

Translation preserves the speaker's voice?

Yes – HeyGen clones the source speaker's voice into the target language and re-syncs lips. Source audio quality matters: clean, single-speaker, 16kHz+.

Related connectors

• Elevenlabs
• Replicate
• Openai