Skip to main content
Model ID 
heygen-avatar-4

​
HeyGen Avatar IV API Usage Guide

​
Overview

HeyGen Avatar IV is HeyGen’s latest avatar video generation model. It produces highly realistic, lip-synced avatar videos from a text script, supporting a wide range of avatars, voices, background styles, and resolutions up to 4K.

​
Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Submit Video Generation Request

​
Base URL

https://console.gmicloud.ai

​
Endpoint

POST /api/v1/ie/requestqueue/apikey/requests

​
Request Format

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": {
      "video_inputs": [
        {
          "character": {
            "type": "avatar",
            "avatar_id": "YOUR_AVATAR_ID",
            "avatar_style": "normal"
          },
          "voice": {
            "type": "text",
            "input_text": "Hello, welcome to HeyGen avatar video generation.",
            "voice_id": "YOUR_VOICE_ID",
            "speed": 1.0,
            "pitch": 0
          }
        }
      ],
      "dimension": {
        "width": 1920,
        "height": 1080
      },
      "caption": false
    }
  }'

​
Request Parameters

​
Top-Level Fields

ParameterTypeRequiredDescriptionDefault
video_inputsarrayYesArray of video clip inputs. Each element defines one avatar segment.-
dimensionobjectNoOutput video resolution {"width": int, "height": int}.{"width": 1280, "height": 720}
captionbooleanNoEnable auto-generated captions on the video.false
titlestringNoOptional title label for the video.""

​
video_inputs[].character

FieldTypeRequiredDescription
typestringYesAvatar type. Options: "avatar", "talking_photo"
avatar_idstringYesUnique ID of the avatar to use. Obtain from GET /v2/avatars.
avatar_stylestringNoLayout style. Options: "normal", "circle", "closeUp". Default: "normal"
scalefloatNoAvatar scale. Range: 0.0–5.0. Default: 1.0
offsetobjectNoPosition offset {"x": float, "y": float}. Default: {"x": 0, "y": 0}

​
video_inputs[].voice

FieldTypeRequiredDescription
typestringYesVoice source type. Options: "text", "audio", "silence"
input_textstringYes (if type=text)Script text for the avatar to speak. Max 5000 characters.
voice_idstringYes (if type=text)Voice ID. Obtain from GET /v2/voices.
speedfloatNoSpeaking speed. Range: 0.5–1.5. Default: 1.0
pitchintegerNoVoice pitch adjustment. Range: -50 to 50. Default: 0
emotionstringNoEmotion style. Options: "Excited", "Friendly", "Serious", "Soothing", "Broadcaster"

​
dimension options

ResolutionWidthHeight
720p1280720
1080p19201080
4K (enterprise only)38402160

​
Response

{
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "model": "heygen-avatar-4",
    "status": "queued",
    "created_at": 1762215580,
    "updated_at": 1762215580,
    "queued_at": 1762215580
}

​
Check Request Status

​
Endpoint

GET /api/v1/ie/requestqueue/apikey/requests/{request_id}

​
Example

curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (completed)

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "org_id": "your-org-id",
  "model": "heygen-avatar-4",
  "status": "success",
  "is_public": false,
  "payload": {
    "video_inputs": [...],
    "dimension": {"width": 1920, "height": 1080},
    "caption": false
  },
  "outcome": {
    "media_urls": [
      {
        "id": "0",
        "url": "https://storage.googleapis.com/your_avatar_video.mp4"
      }
    ],
    "thumbnail_image_url": "https://storage.googleapis.com/your_thumbnail.jpg",
    "duration": 12.5
  },
  "created_at": 1762215580,
  "updated_at": 1762215640,
  "queued_at": 1762215580
}

​
Request Status Values

StatusDescription
queuedRequest is waiting to be processed
processingVideo generation is in progress
successVideo generation completed successfully
failedVideo generation failed
cancelledRequest was cancelled

​
List Your Requests

​
Endpoint

GET /api/v1/ie/requestqueue/apikey/requests?model_id=heygen-avatar-4

​
Example

curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests?model_id=heygen-avatar-4" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get Model Information

​
Endpoint

GET /api/v1/ie/requestqueue/apikey/models/heygen-avatar-4