Model ID

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 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

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

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.

Overview

Model Quickstarts

Agents

Coding Tools

AgentBox Guides

Migration Guides

heygen-avatar-4

HeyGen Avatar IV (v4) API Documentation

1. API Endpoint & Authentication

2. Model Specifications

3. Character Modes

Built-in HeyGen Avatar

Talking Photo (Custom Image)

4. Parameter Reference

5. Example CURL Request

6. Checking Request Status

​HeyGen Avatar IV (v4) API Documentation

​1. API Endpoint & Authentication

​2. Model Specifications

​3. Character Modes

​Built-in HeyGen Avatar

​Talking Photo (Custom Image)

​4. Parameter Reference

​5. Example CURL Request

​6. Checking Request Status

HeyGen Avatar IV (v4) API Documentation

1. API Endpoint & Authentication

2. Model Specifications

3. Character Modes

Built-in HeyGen Avatar

Talking Photo (Custom Image)

4. Parameter Reference

5. Example CURL Request

6. Checking Request Status