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

# Avatar Video (Talking Head)

> Turn one face photo and a script, or your own audio, into a talking-head video

Avatar video turns a single face photo plus a script — or your own audio track — into a
talking-head clip. Pick an avatar model with `model` on `generate_video`; the shared
arguments are on [Generate Video with AI](https://docs.videodb.io/api-reference/generation/generate_video.md).

## Avatar models

| `model` | What it uses | Access |
| - | - | - |
| `heygen` | HeyGen Avatar IV — one face photo, plus a spoken script or your own audio | Pro plans |

`conn.get_generation_models()` lists the models your account can use. More models will be
added to this category; the arguments below are per model.

## HeyGen (`model="heygen"`)

Access: Pro plans. `prompt` is the exact script the avatar speaks, word for word.
`image_url` is a public photo with one clear face.

```python Python theme={null}
from videodb import HeyGenConfig

video = coll.generate_video(
    prompt="Hi, I'm Maya. Here's our new dashboard in under a minute.",
    model="heygen",
    image_url="https://example.com/maya.png",
    aspect_ratio="9:16",
    resolution="720p",
    config=HeyGenConfig(voice="Ivy", talking_style="expressive", caption=True),
)

# Lip-sync to your own audio instead of a script
video = coll.generate_video(
    model="heygen",
    image_url="https://example.com/maya.png",
    config=HeyGenConfig(audio_id="a-123"),
)
```

```javascript Node.js theme={null}
import { HeyGenConfig } from 'videodb';

const video = await coll.generateVideo(
  "Hi, I'm Maya. Here's our new dashboard in under a minute.",
  undefined,
  undefined,
  {
    model: 'heygen',
    imageUrl: 'https://example.com/maya.png',
    aspectRatio: '9:16',
    resolution: '720p',
    config: new HeyGenConfig({ voice: 'Ivy', talkingStyle: 'expressive', caption: true }),
  }
);
```

A plain dict or object with the same keys works as `config` too. Keys are snake\_case in Python and the REST API (`audio_id`, `talking_style`); the Node SDK takes camelCase (`audioId`, `talkingStyle`) and sends them as snake\_case.

| Argument | Values |
| - | - |
| `image_url` | Required. Public URL of a photo with one clear face |
| `prompt` | The script. Up to about 120 seconds of speech (about 1,800 English characters). Not needed with `audio_id` |
| `aspect_ratio` | `16:9` (default), `9:16`, `4:5`, `5:4`, `1:1`, `auto` |
| `resolution` | `360p`, `480p`, `540p`, `720p` (default), `1080p` |

### `config`

| Key | Type | Values |
| - | - | - |
| `voice` | string | A voice name from the list below, exact spelling. Default `Warm Pro Narrator` |
| `audio_id` | string | Your audio ID to lip-sync instead of speaking `prompt`. Up to 120 seconds. Not with `voice` |
| `talking_style` | string | `stable` (default, calm) or `expressive` |
| `expression` | string | `happy` |
| `caption` | boolean | Burn in subtitles. Default `false` |
| `background` | object | `{"type": "color", "value": "#FFFFFF"}`, or `type` `image` / `video` with a public URL as `value` |

Unknown keys and values outside these lists are rejected before anything is generated, with the allowed values in the message.

### Price and time

* **\$0.50 per second** of output video, billed on the actual length, rounded down to whole seconds. The same at every resolution.
* Your balance is checked against the script's estimated length (or the audio's length) before generating.
* A short clip takes about 2 to 5 minutes. For long scripts, pass `callback_url` rather than waiting on the call.

### Voices

`HeyGenConfig.voices` in the SDKs holds a starter set. Every voice:

> [accordion] All 102 voices
>
> | Voice |
> | - |
> | `Warm Pro Narrator` |
> | `Chill Brian` |
> | `Ivy` |
> | `John Doe` |
> | `Monika Sogam` |
> | `Hope ` |
> | `Archer ` |
> | `Brittney` |
> | `Patrick` |
> | `David Castlemore` |
> | `Michael C` |
> | `Adam Stone ` |
> | `Juniper` |
> | `Cassidy ` |
> | `Jessica Anne Bogart` |
> | `Arabella` |
> | `Andrew` |
> | `Spuds Oxley ` |
> | `Grace Elder` |
> | `Helen` |
> | `Canyon Rivers` |
> | `Derya - Lifelike - Excited 🤩` |
> | `Mellow Marcus` |
> | `Jack Sterling - Broadcaster 🎙️` |
> | `Brenda - UGC - 1.mp4` |
> | `Reid` |
> | `Reagan` |
> | `Terry` |
> | `Jenny` |
> | `Radio Rick` |
> | `Denise` |
> | `Tim in car - Excited 🤩` |
> | `Iskander` |
> | `Thompson` |
> | `Delicate Daisy - Excited 🤩` |
> | `Kingston` |
> | `George UGC 1` |
> | `Bold Blake` |
> | `Jane` |
> | `Expressive Evan` |
> | `Marianne - IA` |
> | `Aaron` |
> | `Modern Recipe Host - Voice 1` |
> | `Willow` |
> | `Cute Chloe - Friendly 😊` |
> | `Rafael` |
> | `June - Lifelike` |
> | `Crisp Chloe` |
> | `Slick Simon` |
> | `Nassim - Informative` |
> | `Baritone Ben` |
> | `Maxwell` |
> | `Ellie Faye - Excited 🤩` |
> | `Milani` |
> | `Feisty Fiona - Excited 🤩` |
> | `Professor Dean` |
> | `Rose - UGC - 1.mp4` |
> | `Shona` |
> | `Hudson Wilder` |
> | `Ann - IA` |
> | `Alastair Kensington` |
> | `Oxley` |
> | `Christina` |
> | `Andrew Rizz ` |
> | `Peyton` |
> | `Gerardo - Outdoor` |
> | `Chloe - Lifelike` |
> | `Stephanie` |
> | `Anthony - IA` |
> | `Signal - Voice 1` |
> | `Luca` |
> | `Lisa - Voice 1` |
> | `T.W.Tucker` |
> | `Jack Sullivan - Serious 😐` |
> | `Winter` |
> | `Mireia - Lifelike` |
> | `Georgia` |
> | `Stella` |
> | `Masha - Lifelike` |
> | `Charming Charles - Friendly 😊` |
> | `Serenity` |
> | `Annie - Excited` |
> | `Ralph` |
> | `Bethany` |
> | `Dominic` |
> | `Mason Finn` |
> | `Leena` |
> | `Veteran Victor` |
> | `Tamara` |
> | `Nik Public` |
> | `Calm Chloe` |
> | `Sevik` |
> | `Reilly` |
> | `Raul` |
> | `Imposing Ian` |
> | `Relaxed Ray` |
> | `Dexter - Professional` |
> | `Relaxed Rick` |
> | `Edwin` |
> | `Rupert Blackwood` |
> | `Ginny` |
> | `Hope` |

Some names end with a space or contain an emoji. Copy them exactly.

## Use VideoDB in your agent

VideoDB lets an AI agent watch, search and clip video.

* **Claude**
  [Add VideoDB from the plugin directory](https://videodb.io/claude?utm_source=docs_videodb_io\&utm_medium=docs_link\&utm_campaign=agent_offer\&utm_content=docs:/pages/act/generative-media/avatar-video)
* **ChatGPT**
  [Add VideoDB from the plugin directory](https://videodb.io/chatgpt?utm_source=docs_videodb_io\&utm_medium=docs_link\&utm_campaign=agent_offer\&utm_content=docs:/pages/act/generative-media/avatar-video)
* **Claude Code**

  ```bash wrap theme={null}
  claude mcp add --transport http videodb https://mcp.videodb.io/mcp
  ```
* **Cursor or any MCP client**
  Add the remote MCP server and log in once:

  ```text wrap theme={null}
  https://mcp.videodb.io/mcp
  ```

Free to start: \$20 of credits, no credit card. [Steps for every client](https://docs.videodb.io/pages/mcp/connect.md)


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