[ PROMPT_NODE_24849 ]
Avatars
[ SKILL_DOCUMENTATION ]
# HeyGen Avatars
Avatars are the AI-generated presenters in HeyGen videos. You can use public avatars provided by HeyGen or create custom avatars.
## Previewing Avatars Before Generation
Always preview avatars before generating a video to ensure they match user preferences. Each avatar has preview URLs that can be opened directly in the browser - no downloading required.
### Quick Preview: Open URL in Browser (Recommended)
The fastest way to preview avatars is to open the URL directly in the default browser. **Do not download the image first** - just pass the URL to `open`:
```bash
# macOS: Open URL directly in default browser (no download)
open "https://files.heygen.ai/avatar/preview/josh.jpg"
# Open preview video to see animation
open "https://files.heygen.ai/avatar/preview/josh.mp4"
# Linux: Use xdg-open
xdg-open "https://files.heygen.ai/avatar/preview/josh.jpg"
# Windows: Use start
start "https://files.heygen.ai/avatar/preview/josh.jpg"
```
The `open` command on macOS opens URLs directly in the default browser - it does not download the file. This is the quickest way to let users see avatar previews.
### List Avatars and Open Previews
```typescript
async function listAndPreviewAvatars(openInBrowser = true): Promise {
const response = await fetch("https://api.heygen.com/v2/avatars", {
headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! },
});
const { data } = await response.json();
for (const avatar of data.avatars.slice(0, 5)) {
console.log(`n${avatar.avatar_name} (${avatar.gender})`);
console.log(` ID: ${avatar.avatar_id}`);
console.log(` Preview: ${avatar.preview_image_url}`);
}
// Open preview URLs directly in browser (no download needed)
if (openInBrowser) {
const { execSync } = require("child_process");
for (const avatar of data.avatars.slice(0, 3)) {
// 'open' on macOS opens the URL in default browser - doesn't download
execSync(`open "${avatar.preview_image_url}"`);
}
}
}
```
**Note:** The `open` command passes the URL to the browser - it does not download. The browser fetches and displays the image directly.
### Workflow: Preview Before Generate
1. **List available avatars** - get names, genders, and preview URLs
2. **Open previews in browser** - `open ` for quick visual check
3. **User selects** preferred avatar by name or ID
4. **Get avatar details** for `default_voice_id`
5. **Generate video** with selected avatar
```bash
# Example workflow in terminal
# 1. List avatars (agent shows options)
# 2. Open preview for candidate
open "https://files.heygen.ai/avatar/preview/josh.jpg"
# 3. User says "use Josh"
# 4. Agent gets details and generates
```
### Preview Fields in API Response
| Field | Description |
|-------|-------------|
| `preview_image_url` | Static image of the avatar (JPG) - open in browser |
| `preview_video_url` | Short video clip showing avatar animation |
Both URLs are publicly accessible - no authentication needed to view.
## Listing Available Avatars
### curl
```bash
curl -X GET "https://api.heygen.com/v2/avatars"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
### TypeScript
```typescript
interface Avatar {
avatar_id: string;
avatar_name: string;
gender: "male" | "female";
preview_image_url: string;
preview_video_url: string;
}
interface AvatarsResponse {
error: null | string;
data: {
avatars: Avatar[];
talking_photos: TalkingPhoto[];
};
}
async function listAvatars(): Promise {
const response = await fetch("https://api.heygen.com/v2/avatars", {
headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! },
});
const json: AvatarsResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data.avatars;
}
```
### Python
```python
import requests
import os
def list_avatars() -> list:
response = requests.get(
"https://api.heygen.com/v2/avatars",
headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"]}
)
data = response.json()
if data.get("error"):
raise Exception(data["error"])
return data["data"]["avatars"]
```
## Response Format
```json
{
"error": null,
"data": {
"avatars": [
{
"avatar_id": "josh_lite3_20230714",
"avatar_name": "Josh",
"gender": "male",
"preview_image_url": "https://files.heygen.ai/...",
"preview_video_url": "https://files.heygen.ai/..."
},
{
"avatar_id": "angela_expressive_20231010",
"avatar_name": "Angela",
"gender": "female",
"preview_image_url": "https://files.heygen.ai/...",
"preview_video_url": "https://files.heygen.ai/..."
}
],
"talking_photos": []
}
}
```
## Avatar Types
### Public Avatars
HeyGen provides a library of public avatars that anyone can use:
```typescript
// List only public avatars
const avatars = await listAvatars();
const publicAvatars = avatars.filter((a) => !a.avatar_id.startsWith("custom_"));
```
### Private/Custom Avatars
Custom avatars created from your own training footage:
```typescript
const customAvatars = avatars.filter((a) => a.avatar_id.startsWith("custom_"));
```
### Instant Avatars
Quick avatars created from a single photo or short video:
```typescript
// List instant avatars
const response = await fetch("https://api.heygen.com/v1/instant_avatar.list", {
headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! },
});
const { data } = await response.json();
console.log(data.avatars);
```
## Avatar Styles
Avatars support different rendering styles:
| Style | Description |
|-------|-------------|
| `normal` | Full body shot, standard framing |
| `closeUp` | Close-up on face, more expressive |
| `circle` | Avatar in circular frame (talking head) |
| `voice_only` | Audio only, no video rendering |
### When to Use Each Style
| Use Case | Recommended Style |
|----------|-------------------|
| Full-screen presenter video | `normal` |
| Personal/intimate content | `closeUp` |
| Picture-in-picture overlay | `circle` |
| Small corner widget | `circle` |
| Podcast/audio content | `voice_only` |
| Motion graphics with avatar overlay | `normal` or `closeUp` + transparent bg |
### Using Avatar Styles
```typescript
const videoConfig = {
video_inputs: [
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "normal", // "normal" | "closeUp" | "circle" | "voice_only"
},
voice: {
type: "text",
input_text: "Hello, world!",
voice_id: "1bd001e7e50f421d891986aad5158bc8",
},
},
],
};
```
### Circle Style for Talking Heads
Circle style is ideal for overlay compositions:
```typescript
// Circle avatar for picture-in-picture
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "circle",
},
voice: { ... },
background: {
type: "color",
value: "#00FF00", // Green for chroma key, or use webm endpoint
},
}
```
## Searching and Filtering Avatars
### By Gender
```typescript
function filterByGender(avatars: Avatar[], gender: "male" | "female"): Avatar[] {
return avatars.filter((a) => a.gender === gender);
}
const maleAvatars = filterByGender(avatars, "male");
const femaleAvatars = filterByGender(avatars, "female");
```
### By Name
```typescript
function searchByName(avatars: Avatar[], query: string): Avatar[] {
const lowerQuery = query.toLowerCase();
return avatars.filter((a) =>
a.avatar_name.toLowerCase().includes(lowerQuery)
);
}
const results = searchByName(avatars, "josh");
```
## Avatar Groups
Avatars are organized into groups for better management. Use the v3 APIs for paginated listing with search capabilities.
### List Avatar Groups (v3 - Recommended)
The v3 API provides pagination and search capabilities:
```bash
curl -X GET "https://api.heygen.com/v3/avatar_group.list?page=1&page_size=20&include_public=true"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | 1 | Page number (1-10000) |
| `page_size` | int | 20 | Items per page (1-1000) |
| `query` | string | null | Search query for filtering |
| `include_public` | bool | false | Include public avatars in results |
#### TypeScript
```typescript
interface AvatarGroupItem {
id: string;
name: string;
created_at: number;
num_looks: number;
preview_image: string;
group_type: string;
train_status: string;
default_voice_id: string | null;
}
interface AvatarGroupListResponse {
error: null | string;
data: {
avatar_group_list: AvatarGroupItem[];
total_count: number;
current_page: number;
page_size: number;
};
}
async function listAvatarGroups(
page = 1,
pageSize = 20,
includePublic = true,
query?: string
): Promise {
const params = new URLSearchParams({
page: page.toString(),
page_size: pageSize.toString(),
include_public: includePublic.toString(),
});
if (query) {
params.set("query", query);
}
const response = await fetch(
`https://api.heygen.com/v3/avatar_group.list?${params}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const json: AvatarGroupListResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data;
}
```
### Search Public Avatars (v3)
Search and filter public avatars with pagination:
```bash
curl -X GET "https://api.heygen.com/v3/avatar_groups/search?page=1&page_size=20&query=professional"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | 1 | Page number (1-1000) |
| `page_size` | int | 20 | Items per page (1-1000) |
| `search_tags` | string[] | null | Filter by tags (comma-separated) |
| `query` | string | null | Text search query |
| `list_filter` | string | null | Additional filter criteria |
#### TypeScript
```typescript
async function searchPublicAvatars(
page = 1,
pageSize = 20,
query?: string,
searchTags?: string[]
): Promise {
const params = new URLSearchParams({
page: page.toString(),
page_size: pageSize.toString(),
});
if (query) {
params.set("query", query);
}
if (searchTags?.length) {
params.set("search_tags", searchTags.join(","));
}
const response = await fetch(
`https://api.heygen.com/v3/avatar_groups/search?${params}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const json: AvatarGroupListResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data;
}
// Usage examples
const businessAvatars = await searchPublicAvatars(1, 20, "business");
const femaleAvatars = await searchPublicAvatars(1, 20, undefined, ["female"]);
```
### List Avatar Groups (v2 - Legacy)
```bash
curl -X GET "https://api.heygen.com/v2/avatar_group.list"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
### Get Avatars in a Group
```bash
curl -X GET "https://api.heygen.com/v2/avatar_group/{group_id}/avatars"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
## Using Avatars in Video Generation
### Basic Avatar Usage
```typescript
const videoConfig = {
video_inputs: [
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "normal",
},
voice: {
type: "text",
input_text: "Welcome to our product demo!",
voice_id: "1bd001e7e50f421d891986aad5158bc8",
},
},
],
dimension: { width: 1920, height: 1080 },
};
```
### Multiple Scenes with Different Avatars
```typescript
const multiSceneConfig = {
video_inputs: [
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "normal",
},
voice: {
type: "text",
input_text: "Hi, I'm Josh. Let me introduce my colleague.",
voice_id: "1bd001e7e50f421d891986aad5158bc8",
},
},
{
character: {
type: "avatar",
avatar_id: "angela_expressive_20231010",
avatar_style: "normal",
},
voice: {
type: "text",
input_text: "Hello! I'm Angela. Nice to meet you!",
voice_id: "2d5b0e6a8c3f47d9a1b2c3d4e5f60718",
},
},
],
};
```
## Using Avatar's Default Voice
Many avatars have a `default_voice_id` that's pre-matched for natural results. **This is the recommended approach** rather than manually selecting voices.
### Recommended Flow
```
1. GET /v2/avatars → Get list of avatar_ids
2. GET /v2/avatar/{id}/details → Get default_voice_id for chosen avatar
3. POST /v2/video/generate → Use avatar_id + default_voice_id
```
### Get Avatar Details (v2 API)
Given an `avatar_id`, fetch its details including the default voice:
```bash
curl -X GET "https://api.heygen.com/v2/avatar/{avatar_id}/details"
-H "X-Api-Key: $HEYGEN_API_KEY"
```
#### Response Format
```json
{
"error": null,
"data": {
"type": "avatar",
"id": "josh_lite3_20230714",
"name": "Josh",
"gender": "male",
"preview_image_url": "https://files.heygen.ai/...",
"preview_video_url": "https://files.heygen.ai/...",
"premium": false,
"is_public": true,
"default_voice_id": "1bd001e7e50f421d891986aad5158bc8",
"tags": ["AVATAR_IV"]
}
}
```
#### TypeScript
```typescript
interface AvatarDetails {
type: "avatar";
id: string;
name: string;
gender: "male" | "female";
preview_image_url: string;
preview_video_url: string;
premium: boolean;
is_public: boolean;
default_voice_id: string | null;
tags: string[];
}
async function getAvatarDetails(avatarId: string): Promise {
const response = await fetch(
`https://api.heygen.com/v2/avatar/${avatarId}/details`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const json = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data;
}
// Usage: Get default voice for a known avatar
const details = await getAvatarDetails("josh_lite3_20230714");
if (details.default_voice_id) {
console.log(`Using ${details.name} with default voice: ${details.default_voice_id}`);
} else {
console.log(`${details.name} has no default voice, select manually`);
}
```
#### Complete Example: Generate Video with Any Avatar's Default Voice
```typescript
async function generateWithAvatarDefaultVoice(
avatarId: string,
script: string
): Promise {
// 1. Get avatar details to find default voice
const avatar = await getAvatarDetails(avatarId);
if (!avatar.default_voice_id) {
throw new Error(`Avatar ${avatar.name} has no default voice`);
}
// 2. Generate video with the avatar's default voice
const videoId = await generateVideo({
video_inputs: [{
character: {
type: "avatar",
avatar_id: avatar.id,
avatar_style: "normal",
},
voice: {
type: "text",
input_text: script,
voice_id: avatar.default_voice_id,
},
}],
dimension: { width: 1920, height: 1080 },
});
return videoId;
}
```
### Why Use Default Voice?
1. **Guaranteed gender match** - Avatar and voice are pre-paired
2. **Natural lip sync** - Default voices are optimized for the avatar
3. **Simpler code** - No need to fetch and match voices separately
4. **Better quality** - HeyGen has tested this combination
## Selecting the Right Avatar
### Avatar Categories
HeyGen avatars fall into distinct categories. Match the category to your use case:
| Category | Examples | Best For |
|----------|----------|----------|
| **Business/Professional** | Josh, Angela, Wayne | Corporate videos, product demos, training |
| **Casual/Friendly** | Lily, various lifestyle avatars | Social media, informal content |
| **Themed/Seasonal** | Holiday-themed, costume avatars | Specific campaigns, seasonal content |
| **Expressive** | Avatars with "expressive" in name | Engaging storytelling, dynamic content |
### Selection Guidelines
**For business/professional content:**
- Choose avatars with neutral attire (business casual or formal)
- Avoid themed or seasonal avatars (holiday costumes, casual clothing)
- Preview the avatar to verify professional appearance
- Consider your audience demographics when selecting gender and appearance
**For casual/social content:**
- More flexibility in avatar choice
- Themed avatars can work for specific campaigns
- Match avatar energy to content tone
### Common Mistakes to Avoid
1. **Using themed avatars for business content** - A holiday-themed avatar looks unprofessional in a product demo
2. **Not previewing before generation** - Always `open ` to verify appearance
3. **Ignoring avatar style** - A `circle` style avatar may not work for full-screen presentations
4. **Mismatched voice gender** - Always use the avatar's `default_voice_id` or match genders manually
### Selection Checklist
Before generating a video:
- [ ] Previewed avatar image/video in browser
- [ ] Avatar appearance matches content tone (professional vs casual)
- [ ] Avatar style (`normal`, `closeUp`, `circle`) fits the video format
- [ ] Voice gender matches avatar gender
- [ ] Using `default_voice_id` when available
## Helper Functions
### Get Avatar by ID
```typescript
async function getAvatarById(avatarId: string): Promise {
const avatars = await listAvatars();
return avatars.find((a) => a.avatar_id === avatarId) || null;
}
```
### Validate Avatar ID
```typescript
async function isValidAvatarId(avatarId: string): Promise {
const avatar = await getAvatarById(avatarId);
return avatar !== null;
}
```
### Get Random Avatar
```typescript
async function getRandomAvatar(gender?: "male" | "female"): Promise {
let avatars = await listAvatars();
if (gender) {
avatars = avatars.filter((a) => a.gender === gender);
}
const randomIndex = Math.floor(Math.random() * avatars.length);
return avatars[randomIndex];
}
```
## Common Avatar IDs
Some commonly used public avatar IDs (availability may vary):
| Avatar ID | Name | Gender |
|-----------|------|--------|
| `josh_lite3_20230714` | Josh | Male |
| `angela_expressive_20231010` | Angela | Female |
| `wayne_20240422` | Wayne | Male |
| `lily_20230614` | Lily | Female |
Always verify avatar availability by calling the list endpoint before using.
Source: claude-code-templates (MIT). See About Us for full credits.