# AI Avatar

> Generate a talking-avatar video from a HeyGen avatar (or a raw image) + voice + script, or wired audio.

## Overview

The AI Avatar node creates a talking-head video using HeyGen. You supply either a text script (HeyGen's built-in TTS delivers the voice) or a pre-recorded audio track. Both paths produce a video of the chosen source speaking the content.

Two **source modes** control where the visual comes from:

| Source | What you provide | Notes |
|--------|-----------------|-------|
| **Avatar** (`avatarSource: avatar`, default) | A HeyGen avatar look picked from the in-node avatar picker | Animated by the Avatar IV / Avatar V engine |
| **Image** (`avatarSource: image`) | A raw image — wired into the node's Image input, pasted as a URL, or uploaded | Animates your own photo/character directly. No avatar creation or training needed, so it works without a higher HeyGen tier. The engine selector is hidden (image mode uses its own engine) |

Both source modes support the same speech modes, voice tuning, background, captions, and motion controls. Image mode is billed identically to Avatar IV (it is IV-class).

Two speech modes:

| Mode | What you provide | Voice |
|------|-----------------|-------|
| **Script + Voice** (`speechMode: text`) | A text script (up to 5,000 characters) and a voice ID picked from the in-node voice picker | HeyGen TTS, driven by the chosen voice and optional voice speed |
| **Wired Audio** (`speechMode: audio`) | An audio file wired to the `audio` input handle | Exactly as recorded — no TTS. Audio inputs are capped at 10 minutes (600s); longer audio is automatically trimmed to 600s (you'll see a notice on the result) |

## Selecting an Avatar and Voice

The config panel includes two rich pickers:

- **Avatar picker** — searchable tile grid fed live from the HeyGen API. Filters: Public / Personal / Group. Preview thumbnails show how the avatar looks.
- **Voice picker** (text mode only) — searchable list of all available HeyGen voices with language and accent filters. Click the preview icon to hear a sample before selecting.

Both pickers return empty when HeyGen is not configured for the deployment; an "HeyGen API not configured" notice appears in that case.

## Configuration

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| Source | Select | `avatar` | `avatar` = HeyGen avatar look; `image` = animate a raw image |
| Speech Mode | Select | `text` | `text` = script + voice; `audio` = wired audio input |
| Avatar | Picker | — | HeyGen avatar ID (required in avatar source mode) |
| Source Image | Image input / URL / Upload | — | Source image (required in image source mode) — wire an image node into the Image input, paste a URL, or upload |
| Script | Textarea | — | Spoken text (required in text mode, max 5,000 chars) |
| Voice | Picker | — | HeyGen voice ID (required in text mode) |
| Voice Speed | Slider | 1.0 | Speaking rate, range 0.5–1.5 (text mode only) |
| Engine | Select | `avatar-iv` | `avatar-iv` = Avatar IV; `avatar-v` = Avatar V (premium). Avatar source mode only — hidden in image source mode |
| Resolution | Select | `720p` | Output resolution: `720p`, `1080p`, `4k` |
| Aspect Ratio | Select | `16:9` | `16:9` (landscape) or `9:16` (portrait / vertical) |
| Captions | Toggle | off | Burn auto-generated captions into the video |

## Inputs & Outputs

**Inputs:**
- Image (optional, required when `avatarSource = image`) — source image to animate (also settable via URL/upload in the config panel)
- Script (optional) — verbatim spoken text wired from a text producer (text mode)
- Audio (optional, required when `speechMode = audio`) — pre-recorded audio track

**Outputs:**
- Generated video URL

## Credit Pricing

Credits are metered by the **actual length** of the generated video. A hold is placed when the job starts; any unused amount is **refunded automatically** when the job completes — so you only pay for the seconds you get.

### Approximate cost

| Engine | 720p | 1080p | 4K |
|--------|-----:|------:|---:|
| Avatar IV | ~3.8 credits/sec | ~5 credits/sec | ~10 credits/sec |
| Avatar V | ~5 credits/sec | ~6.3 credits/sec | ~12.5 credits/sec |

Examples (Avatar IV, 720p): a **30-second** clip ≈ **113 credits**; a **1-minute** clip ≈ **225 credits**. Higher resolutions and Avatar V cost proportionally more. Captions add no extra cost.

> The exact credit cost is shown in the editor before you run, and the final charge always reflects the real clip length.

### Reserve & refund

- **Text mode** — the upfront hold is estimated from your script length and voice speed (slower speech reserves a bit more). You're charged for the actual generated length; the remainder is refunded.
- **Audio mode** — the hold is sized from your uploaded clip's measured length, so a short voiceover reserves only a small amount (a few seconds' worth), not a large flat block. Audio is capped at 10 minutes (600s): a longer clip is automatically trimmed to 600s and the hold is sized at that 10-minute cap. As always, you're charged only for the real generated length and any surplus is refunded.

## Graceful Degradation

If HeyGen is not configured for the deployment:
- The avatar picker and voice picker both show empty with an explanatory notice
- Attempting to run the node returns an error: `heygen_not_configured`

## Best Practices

- Use clear, natural-language scripts under 5,000 characters for best TTS quality
- Preview voices in the picker before wiring a long script
- Start with Avatar IV 720p for drafts; upgrade to 1080p or Avatar V for final delivery
- Captions add no extra credit cost

## Common Use Cases

- Product demos with a consistent presenter avatar
- Personalized video messages at scale
- Multilingual spokesperson videos (change script language + matching HeyGen voice)
- News-style or explainer videos

## Tips

- Voice speed below 1.0 increases the estimated reserve bucket (slower speech → longer clip)
- The 9:16 aspect ratio is optimized for TikTok, Instagram Reels, and YouTube Shorts
- Wired-audio mode is useful when you want precise pacing or have a pre-recorded voiceover
- Connect a Text to Speech node upstream to build a fully scripted pipeline that bypasses HeyGen TTS costs