> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/rest-api-reference/tools/generate-avatar/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Generate avatar clip

POST https://api.videogen.io/v1/tools/generate-avatar
Content-Type: application/json

Generate a talking-head avatar video by pairing an ACTOR entity with an audio file, typically from a prior text-to-speech result.

Reference: https://docs.videogen.io/rest-api-reference/tools/generate-avatar

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Body (application/json)

This endpoint expects a GenerateAvatarRequest.

- `actorEntityId` (string, required) — The id of a built-in stock actor or an ACTOR entity (e.g. `vg_enti_...`) with an image reference.
- `audioFileId` (string, required) — File id of an AUDIO file (e.g. `vg_file_...`), typically from a prior text-to-speech result. Upload a file first via `POST /v1/files/upload` or generate one with `POST /v1/tools/text-to-speech`, then pass the returned id here.
- `avatarQuality` (enum, optional) — Avatar generation quality tier. Optional; when omitted, your account's Default AI quality for avatars is used.
  - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
- `watermarkMode` (enum, optional, default: AUTO) — Controls whether the VideoGen watermark is applied to the output. `AUTO` applies the watermark unless you have a Pro plan. `VIDEO_GEN` always applies it. `NONE` removes the watermark (requires Pro; returns an error if you don't have it).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `numResults` (integer, optional, default: 1) — Number of output results to generate. Defaults to 1.
- `isOutputTemporary` (boolean, optional, default: false) — When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false.
- `hideFromUi` (boolean, optional, default: false) — When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

## Response

### 202

Execution accepted; poll until complete.

- `toolExecutionId` (string, required) — Execution id (e.g. `vg_tool_...`).

## Examples

**Request**

```json
{
  "actorEntityId": "vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
  "audioFileId": "vg_file_obLD1OX2eJCrEs0071Z4kA",
  "avatarQuality": "HIGH"
}
```

**Response**

```json
{
  "toolExecutionId": "vg_tool_ccm3abc123defcm3xyz789ghi"
}
```

**SDK Code**

```typescript
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.tools.generateAvatar({
  actorEntityId: "vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
  avatarQuality: "HIGH",
  audioFileId: "vg_file_obLD1OX2eJCrEs0071Z4kA",
});
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.tools.generate_avatar(
    actor_entity_id="vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
    avatar_quality="HIGH",
    audio_file_id="vg_file_obLD1OX2eJCrEs0071Z4kA",
)
```

> HTTP API with TypeScript and Python SDKs for generating image, video, and audio assets with VideoGen.