Skip to main content
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(PhotoAvatar),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

ParameterTypeRequiredDescription
avatar_idstringNo*HeyGen built-in avatar ID. Required if not using talking_photo_id.
talking_photo_idstringNo*Uploaded photo ID for talking photo mode.
avatar_stylestringNoAvatar layout: normal, circle, closeUp. Default: normal.
input_textstringYesScript for the avatar to speak (max 5000 chars).
voice_idstringYesVoice ID (obtain from HeyGen voice library).
speedfloatNoSpeaking speed 0.5–1.5. Default: 1.0.
pitchintegerNoVoice pitch -50 to 50. Default: 0.
emotionstringNoExcited, Friendly, Serious, Soothing, Broadcaster.
durationintegerNoEstimated duration in seconds (used for price estimate only).
captionbooleanNoEnable 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.