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

# heygen-avatar-4

> API usage guide for heygen-avatar-4.

{/* source_model_id: heygen-avatar-4 */}

{/* source_updated_at: 1781739217 */}

**Model ID**

```bash theme={null}
heygen-avatar-4
```

**Calling method:** async

# HeyGen Avatar IV (v4) API Documentation

HeyGen Avatar IV generates highly realistic, lip-synced avatar videos from a text script. Supports HeyGen's built-in avatars and custom talking photos.

## 1. API Endpoint & Authentication

Base URL: [https://console.gmicloud.ai](https://console.gmicloud.ai)
Endpoint: POST /api/v1/ie/requestqueue/apikey/requests
Header:
Authorization: Bearer YOUR\_API\_KEY
Content-Type: application/json

## 2. Model Specifications

* Pricing: $0.05/sec (Photo Avatar), $0.0667/sec (Digital Twin / Studio)
* Resolution: up to 1080p (4K for enterprise)
* Features: Lip-sync, Talking Photo, Multi-segment

## 3. Character Modes

### Built-in HeyGen Avatar

Provide `avatar_id` (obtain from HeyGen avatar library).

### Talking Photo (Custom Image)

Provide `talking_photo_id` (upload image via HeyGen API to get an ID). The model animates the face to lip-sync with the voice.

## 4. Parameter Reference

| Parameter                                              | Type    | Required | Description                                                          |
| :----------------------------------------------------- | :------ | :------- | :------------------------------------------------------------------- |
| avatar\_id                                             | string  | No\*     | HeyGen built-in avatar ID. Required if not using talking\_photo\_id. |
| talking\_photo\_id                                     | string  | No\*     | Uploaded photo ID for talking photo mode.                            |
| avatar\_style                                          | string  | No       | Avatar layout: normal, circle, closeUp. Default: normal.             |
| input\_text                                            | string  | Yes      | Script for the avatar to speak (max 5000 chars).                     |
| voice\_id                                              | string  | Yes      | Voice ID (obtain from HeyGen voice library).                         |
| speed                                                  | float   | No       | Speaking speed 0.5–1.5. Default: 1.0.                                |
| pitch                                                  | integer | No       | Voice pitch -50 to 50. Default: 0.                                   |
| emotion                                                | string  | No       | Excited, Friendly, Serious, Soothing, Broadcaster.                   |
| duration                                               | integer | No       | Estimated duration in seconds (used for price estimate only).        |
| caption                                                | boolean | No       | Enable auto-generated captions. Default: false.                      |
| \*One of avatar\_id or talking\_photo\_id is required. |         |          |                                                                      |

## 5. Example CURL Request

```bash theme={null}
curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-4",
    "payload": {
      "avatar_id": "Abigail_expressive_2024112501",
      "avatar_style": "normal",
      "input_text": "Hello! Welcome to GMI Cloud.",
      "voice_id": "2d5b0e6cf36f460aa7fc47e3eee4ba54",
      "speed": 1.0
    }
  }'
```

## 6. Checking Request Status

```bash theme={null}
Endpoint: GET /api/v1/ie/requestqueue/apikey/requests/{request_id}
```

* queued: Request is waiting to be processed.
* processing: Video generation is in progress.
* success: Generation completed. URL available in outcome.media\_urls.
* failed: Video generation failed.