MaaS_HG_video_translate_v3

Get supported translation languages

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations/languages

Request Parameters

None

Response Parameters

Field	Type	Description
data.languages	string[]	List of supported target language names, such as "Chinese (Simplified)", "Spanish"
error	string	Display error message when the request fails; display null when the request succeeds

Request Example

Request

curl --request GET \
     --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations/languages' \
     --header 'Authorization: Bearer XX'

Response

{
  "data": {
    "languages": ["English", "Chinese (Simplified)", "Spanish", "French"]
  }
}

---

Upload creatives

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/assets

Request Parameters

Content-Type: multipart/form-data

Field	Type	Required	Description
file	binary	is	Files to be uploaded must be no larger than 32 MB and support png / jpeg / mp4 / webm / mp3 / wav / pdf

Response Parameters

Field	Type	Description
error	string	Display error message when the request fails; display null when the request succeeds
code	integer	Status code, 100 indicates success
data.asset_id	string	Unique ID of creatives; fill in when creating a translation taskvideo.asset_id(type="asset_id")
data.url	string	Creative Access URL
data.mime_type	string	MIME type, such as video/mp4
data.size_bytes	long	File Size (ByteDance)
message	string	Result Explanation

Request Example

Request

curl --request POST \
     --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/assets' \
     --header 'Authorization: Bearer XX' \
     --form 'file=@/path/to/video.mp4'

Response

{
  "code": 100,
  "data": {
    "asset_id": "asset-xyz789",
    "url": "https://resource2.heygen.ai/video/asset-xyz789/original.mp4",
    "mime_type": "video/mp4",
    "size_bytes": 10485760
  },
  "message": "success"
}

---

Create a video translation task

Asynchronous Interface : Returns a list of subtask IDs after the call, and polls via "3.6 Query Video Translation Status" until the status becomes success. Supports specifying multiple target languages at once, with each language generating an independent video_translation_id.

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations

Request Parameters

Field	Type	Required	Description
video	object	is	Video source, choose one of two formats (see instructions below)
video.type	string	is	"url" or "asset_id"
video.url	string	Required condition	Fill in when type="url"; supports direct links, Google Drive, and YouTube
video.asset_id	string	Required condition	Fill in when type="asset_id"; use the asset_id returned after uploading via POST /v3/assets
output_languages	string[]	is	List of target languages, e.g. ["Chinese (Simplified)", "Spanish"]; each language generates an independent subtask
input_language	string	No	Source language; if not provided, it will be automatically detected
title	string	No	Video Title (for HeyGen Backend Display)
translate_audio_only	boolean	No	true: Only translate the soundtrack without lip-syncing (suitable for videos where the speaker is not visible); default false
speaker_num	integer	No	Number of speakers in the video
mode	string	No	Translation Quality:speed (default, fast) / precision (high precision, longer time)
enable_dynamic_duration	boolean	No	Dynamic duration adjustment enhances the smoothness between languages with different speaking speeds; default false
keep_the_same_format	boolean	No	Keep the output format the same as the input video; defaultfalse
enable_caption	boolean	No	Whether to generate subtitle files; default false
disable_music_track	boolean	No	Remove the background music; default false
enable_speech_enhancement	boolean	No	Voice Enhancement; Default false

Response Parameters

Field	Type	Description
error	string	Display error message when the request fails; display null when the request succeeds
code	integer	Status code, 100 indicates success
data.video_translation_ids	string[]	Subtask ID list, one for each target language; query the specific language and status of each subtask via Interface 3.6
message	string	Result Explanation

Request Example

Request (URL format)

curl --request POST \
     --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations' \
     --header 'Authorization: Bearer XX' \
     --header 'Content-Type: application/json' \
     --data '{
       "video": { "type": "url", "url": "https://example.com/video.mp4" },
       "output_languages": ["Chinese (Simplified)", "Spanish"],
       "mode": "speed",
       "translate_audio_only": false
     }'

Request (in asset_id format)

curl --request POST \
     --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations' \
     --header 'Authorization: Bearer XX' \
     --header 'Content-Type: application/json' \
     --data '{
       "video": { "type": "asset_id", "asset_id": "06484665e55e45dcaf9e331e8ac258cc" },
       "output_languages": ["Chinese (Simplified)", "Spanish"]
     }'

Response

{
  "code": 100,
  "data": {
    "video_translation_ids": ["vtrans-001", "vtrans-002"]
  },
  "message": "success"
}

---

Query video translation status

Asynchronous Interface : Poll this interface until data.status becomes success. Each video_translation_id needs to be queried separately.

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations/{id}

Request Parameters

Field	Type	Required	Description
id	string (path parameter)	is	Video Translation Subtask ID (video_translation_id)

Response Parameters

Field	Type	Description
error	string	Display error message when the request fails; display null when the request succeeds
data.id	string	Translation Task ID
data.status	string	Task Status:pending / running / completed / failed
data.output_language	string	Target Language
data.input_language	string	Source language (automatically detected or specified)
data.duration	float	Video duration (seconds); returned when status=completed
data.translate_audio_only	boolean	Whether to translate only the soundtrack
data.video_url	string	Video download URL after translation is completed; returned when status=completed
data.audio_url	string	Audio download URL after translation is completed; returned when status=completed
data.srt_caption_url	string	SRT subtitle download URL; returned when enable_caption=true and completed
data.vtt_caption_url	string	VTT subtitle download URL; returned when enable_caption=true and completed
data.title	string	Video Title
data.failure_message	string	Description of failure reason; returned when status=failed
data.created_at	integer	Creation Time (Unix Timestamp)

Request Example

Request

curl --request GET \
     --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/v3/video-translations/vtrans-001' \
     --header 'Authorization: Bearer XX'

Response (Processing)

{
  "data": {
    "id": "vtrans-001",
    "status": "running",
    "output_language": "Chinese (Simplified)",
    "title": "My Video"
  }
}

Response (Completed)

{
  "data": {
    "id": "vtrans-001",
    "status": "completed",
    "output_language": "Chinese (Simplified)",
    "input_language": "English",
    "duration": 32.5,
    "video_url": "https://files.heygen.ai/output/vtrans-001.mp4",
    "title": "My Video"
  }
}

Response (Failure)

{
  "data": {
    "id": "vtrans-001",
    "status": "failed",
    "output_language": "Chinese (Simplified)",
    "failure_message": "Translation failed due to unsupported content."
  }
}

Digital Human User Guide

It is recommended to use Avatar-related interfaces according to the following process:

1. get avatar_id（Look ID）

2. Call the "Create Photo Avatar" API to create a new digital human; or

3. Call the List Avatar Faces/Get Single Avatar Faces interface to get the ID of an existing Look from the returned data [] .id(or data.id).

4. Determine whether the avatar_id comes with audio information

5. Check the default_voice_id field in the Look details:

   • has a value (commonly found in platform-preconfigured studio_avatar, etc.): The Avatar has been bound to the default voice. When creating a video, simply pass script (oral endorsement text), no need for audio_url / audio_asset_id and other pre-recorded audio fields.

   • Empty/null (through "Create Photo Avatar" new photo_avatar must belong to this category ): Avatar does not come with voice information, when creating a video must provide additional audio imported parameters - scriptand audio_url/ audio_asset_id choose one , not all omitted.

---

MaaS_HG_Video_Generation_Avatar IV

1. List Avatar groups

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars

Request Parameters

Field	Type	Required	Description
endpointPath	string	is	Path parameter, model access point identifier
ownership	string	No	Ownership Filtering
limit	integer	No	Number of items returned per page
token	string	No	Pagination cursor, used to retrieve the next page

Response Parameters

Field	Type	Description
data	array	Avatar Group List
data[].id	string	Group ID
data[].name	string	Group Name
data[].created_at	long	Creation Time (Unix Timestamp, milliseconds)
data[].looks_count	integer	Number of Looks under this group
data[].preview_image_url	string	Preview Image URL
data[].preview_video_url	string	Preview Video URL
data[].gender	string	Gender
data[].default_voice_id	string	Default Voice ID
data[].consent_status	string	Authorization Status
data[].status	string	Training Status (Private Avatar Only):processing / pending_consent / failed / completed
data[].error	object	Error message (if any)
data[].error.code	string	Error Code
data[].error.message	string	Error Description
has_more	boolean	Is there a next page?
next_token	string	Next page pagination cursor

Request Example

Request

curl --request GET \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars?ownership=private&limit=20' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Response

{
  "data": [
    {
      "id": "grp_abc123",
      "name": "My Photo Avatar",
      "created_at": 1717843200000,
      "looks_count": 3,
      "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
      "preview_video_url": "https://resource.heygen.com/preview/xxx.mp4",
      "gender": "female",
      "default_voice_id": "voice_001",
      "consent_status": "approved",
      "status": "completed",
      "error": null
    }
  ],
  "has_more": false,
  "next_token": null
}

---

2. Create Photo Avatar

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars

Content-Type：application/json

Request Parameters

Field	Type	Required	Instructions
endpointPath	string	is	Path parameter, model access point identifier
type	string	is	Fixed value photo
name	string	No	Avatar Name
file	object	is	Image assets support three methods: url / asset_id / base64
file.type	string	is	Input Method:url / asset_id / base64
file.url	string	Required condition	Required when file.type=url; publicly accessible HTTPS image URL
file.asset_id	string	Required condition	Required when file.type=asset_id; HeyGen Asset ID
file.media_type	string	Required condition	Required when file.type=base64; MIME type, e.g., image/png
file.data	string	Required condition	Required when file.type=base64; base64 encoded content
avatar_group_id	string	No	The ID of the Avatar Group to which it belongs; if not provided, a new group will be automatically created

Response Parameters

Field	Type	Description
error	object / null	Error message when failed; null when successful
data.avatar_item	object	Information of the created Avatar Look
data.avatar_item.id	string	Look ID (prefix lk_) is passed as avatar_id when creating a video
data.avatar_item.name	string	Look Name
data.avatar_item.avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data.avatar_item.group_id	string	Group ID
data.avatar_item.preview_image_url	string	Preview Image URL
data.avatar_item.preview_video_url	string	Preview Video URL
data.avatar_item.gender	string	Gender
data.avatar_item.tags	array	Tag List
data.avatar_item.tags[]	string	Label
data.avatar_item.default_voice_id	string	Default Voice ID
data.avatar_item.supported_api_engines	array	Supported engine versions, such as ["avatar_v", "avatar_iv"]
data.avatar_item.supported_api_engines[]	string	Engine Version
data.avatar_item.image_width	integer	Image Width (pixels)
data.avatar_item.image_height	integer	Image Height (pixels)
data.avatar_item.preferred_orientation	string	Recommended Orientation:portrait / landscape / square
data.avatar_item.status	string	Training Status (Private Avatar Only)
data.avatar_item.error	object	Error message (if any)
data.avatar_group	object	Information of the affiliated Avatar Group
data.avatar_group.id	string	Group ID
data.avatar_group.name	string	Group Name
data.avatar_group.created_at	long	Creation Time (Unix Timestamp, milliseconds)
data.avatar_group.looks_count	integer	Look Quantity
data.avatar_group.preview_image_url	string	Preview Image URL
data.avatar_group.preview_video_url	string	Preview Video URL
data.avatar_group.gender	string	Gender
data.avatar_group.default_voice_id	string	Default Voice ID
data.avatar_group.consent_status	string	Authorization Status
data.avatar_group.status	string	Training Status (Private Avatar Only)
data.avatar_group.error	object	Error message (if any)

Request Example

Request

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "photo",
    "name": "My Avatar",
    "file": {
      "type": "url",
      "url": "https://example.com/avatar-photo.jpg"
    }
  }'

Response

{
  "error": null,
  "data": {
    "avatar_item": {
      "id": "lk_abc123def456",
      "name": "My Avatar",
      "avatar_type": "photo_avatar",
      "group_id": "grp_abc123",
      "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
      "preview_video_url": null,
      "gender": "female",
      "tags": [],
      "default_voice_id": "voice_001",
      "supported_api_engines": ["avatar_iv"],
      "image_width": 1024,
      "image_height": 1024,
      "preferred_orientation": "portrait",
      "status": "completed",
      "error": null
    },
    "avatar_group": {
      "id": "grp_abc123",
      "name": "My Avatar",
      "created_at": 1717843200000,
      "looks_count": 1,
      "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
      "preview_video_url": null,
      "gender": "female",
      "default_voice_id": "voice_001",
      "consent_status": "approved",
      "status": "completed",
      "error": null
    }
  }
}

---

3. List Avatar Looks

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/looks

Request Parameters

Field	Type	Required	Description
endpointPath	string	is	Path parameter, model access point identifier
group_id	string	No	Filter by Avatar Group ID
avatar_type	string	No	Filter by Avatar Type:studio_avatar / digital_twin / photo_avatar
ownership	string	No	Ownership Filtering
limit	integer	No	Number of items returned per page
token	string	No	Pagination cursor, used to retrieve the next page

Response Parameters

Field	Type	Description
data	array	Avatar Look List
data[].id	string	Look ID (prefix lk_) is passed as avatar_id when creating a video
data[].name	string	Look Name
data[].avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data[].group_id	string	Group ID
data[].preview_image_url	string	Preview Image URL
data[].preview_video_url	string	Preview Video URL
data[].gender	string	Gender
data[].tags	array	Tag List
data[].tags[]	string	Label
data[].default_voice_id	string	Default Voice ID
data[].supported_api_engines	array	Supported Engine Version
data[].supported_api_engines[]	string	Engine version, such as avatar_v, avatar_iv
data[].image_width	integer	Image Width (pixels)
data[].image_height	integer	Image Height (pixels)
data[].preferred_orientation	string	Recommended Orientation:portrait / landscape / square
data[].status	string	Training Status (Private Avatar Only)
data[].error	object	Error message (if any)
has_more	boolean	Is there a next page?
next_token	string	Next page pagination cursor

Request Example

Request

curl --request GET \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/looks?group_id=grp_abc123&avatar_type=photo_avatar&limit=20' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Response

{
  "data": [
    {
      "id": "lk_abc123def456",
      "name": "My Avatar",
      "avatar_type": "photo_avatar",
      "group_id": "grp_abc123",
      "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
      "preview_video_url": "https://resource.heygen.com/preview/xxx.mp4",
      "gender": "female",
      "tags": ["formal"],
      "default_voice_id": "voice_001",
      "supported_api_engines": ["avatar_iv"],
      "image_width": 1024,
      "image_height": 1024,
      "preferred_orientation": "portrait",
      "status": "completed",
      "error": null
    }
  ],
  "has_more": false,
  "next_token": null
}

---

4. Get the appearance of a single Avatar

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/looks/{lookId}

Request Parameters

Field	Type	Required	Instructions
endpointPath	string	is	Path parameter, model access point identifier
lookId	string	is	Path parameter, Avatar Look ID

Response Parameters

Field	Type	Instructions
error	object / null	Error message when failed; null when successful
data.id	string	Look ID (prefix lk_) is passed as avatar_id when creating a video
data.name	string	Look Name
data.avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data.group_id	string	Group ID
data.preview_image_url	string	Preview Image URL
data.preview_video_url	string	Preview Video URL
data.gender	string	Gender
data.tags	array	Tag List
data.tags[]	string	Label
data.default_voice_id	string	Default Voice ID
data.supported_api_engines	array	Supported Engine Version
data.supported_api_engines[]	string	Engine Version
data.image_width	integer	Image Width (pixels)
data.image_height	integer	Image Height (pixels)
data.preferred_orientation	string	Recommended Orientation:portrait / landscape / square
data.status	string	Training Status (Private Avatar Only)
data.error	object	Error message (if any)

Request Example

Request

curl --request GET \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/looks/lk_abc123def456' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Response

{
  "error": null,
  "data": {
    "id": "lk_abc123def456",
    "name": "My Avatar",
    "avatar_type": "photo_avatar",
    "group_id": "grp_abc123",
    "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
    "preview_video_url": "https://resource.heygen.com/preview/xxx.mp4",
    "gender": "female",
    "tags": ["formal"],
    "default_voice_id": "voice_001",
    "supported_api_engines": ["avatar_iv"],
    "image_width": 1024,
    "image_height": 1024,
    "preferred_orientation": "portrait",
    "status": "completed",
    "error": null
  }
}

---

5. Get a single Avatar group

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/{groupId}

Request Parameters

Field	Type	Required	Instructions
endpointPath	string	is	Path parameter, model access point identifier
groupId	string	is	Path parameter, Avatar Group ID

Response Parameters

Field	Type	Instructions
error	object / null	Error message when failed; null when successful
data.id	string	Group ID
data.name	string	Group Name
data.created_at	long	Creation Time (Unix Timestamp, milliseconds)
data.looks_count	integer	Number of Looks under this group
data.preview_image_url	string	Preview Image URL
data.preview_video_url	string	Preview Video URL
data.gender	string	Gender
data.default_voice_id	string	Default Voice ID
data.consent_status	string	Authorization Status
data.status	string	Training Status (Private Avatar Only):processing / pending_consent / failed / completed
data.error	object	Error message (if any)
data.error.code	string	Error Code
data.error.message	string	Error Description

Request Example

Request

curl --request GET \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/avatars/grp_abc123' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Response

{
  "error": null,
  "data": {
    "id": "grp_abc123",
    "name": "My Photo Avatar",
    "created_at": 1717843200000,
    "looks_count": 3,
    "preview_image_url": "https://resource.heygen.com/preview/xxx.jpg",
    "preview_video_url": "https://resource.heygen.com/preview/xxx.mp4",
    "gender": "female",
    "default_voice_id": "voice_001",
    "consent_status": "approved",
    "status": "completed",
    "error": null
  }
}

---

6. Create an Avatar video

Asynchronous task interface; after successful creation, it returns video_id, and the result is polled through the "Query Video Generation Status" interface.

Audio Description

The avatar_id (Look ID) obtained through the "Create Photo Avatar" interface does not come with audio/voice information (the default_voice_id in the response is empty). When creating a video using this ID, you must provide one of the following audio fields in the request body:

method	Field	Instructions
TTS Text-driven	script	Pass in voice-over text, which will be synthesized into speech by the system; can be used in conjunction with voice_settings to adjust speed/pitch/volume
Pre-recorded audio URL	audio_url	Pass in the URL of a publicly accessible audio file
Pre-recorded audio assets	audio_asset_id	Pass in the HeyGen asset ID (audio creatives need to be uploaded first)

script and audio_url are mutually exclusive and cannot be passed in simultaneously.

If avatar_id comes from the List/Look details and default_voice_id has a value (such as platform-predefined Avatars), when creating a video, just pass script, no need for audio_url/audio_asset_id; if default_voice_id is empty, then script or pre-recorded audio fields must be provided as shown in the table above.

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos

Content-Type：application/json

Request Parameters

Field	Type	Required	Instructions
endpointPath	string	is	Path parameter, model access point identifier
type	string	is	Fixed Value avatar
avatar_id	string	is	Look ID, from the id field of "Create Photo Avatar", "List Avatar Appearances", or "Get Single Avatar Appearance"
title	string	No	Video Title
resolution	string	No	Resolution:4k / 1080p / 720p
aspect_ratio	string	No	Aspect Ratio:16:9 / 9:16
fit	string	No	Screen adaptation method:contain / cover
background	object	No	Background Settings
background.type	string	No	Background Type:color / image
background.value	string	Required condition	Fill in when background.type=color; hexadecimal color value, e.g., #ffffff
background.url	string	Required condition	Fill in when background.type=image; Image URL (choose one of asset_id)
background.asset_id	string	Required condition	Fill in when background.type=image; HeyGen Asset ID (choose one of url)
remove_background	boolean	No	Whether to remove the background
callback_url	string	No	Task Completion Callback URL
callback_id	string	No	Client Custom Callback ID
output_format	string	No	Output format:mp4 / webm; default mp4
script	string	Required condition	TTS oral endorsement text is mutually exclusive with audio_url. default_voice_id is required when empty (including the ID obtained from "Create Photo Avatar").
audio_url	string	Required condition	Pre-recorded audio URL, mutually exclusive with script. default_voice_id is required when empty (including the ID obtained from "Create Photo Avatar") (either this or script is required)
audio_asset_id	string	Required condition	Pre-recorded audio asset ID; mutually exclusive with script, applicable to scenarios where audio creatives have been uploaded.default_voice_id must be provided in conjunction with either script / audio_url when it is empty
voice_settings	object	No	Voice parameters; when used in conjunction with script, it can adjust the speaking speed, pitch, and volume
voice_settings.speed	double	No	Speech Rate
voice_settings.pitch	double	No	tone
voice_settings.volume	double	No	Volume
motion_prompt	string	No	Control Avatar limb movements (photo_avatar + for Avatar IV only)
expressiveness	string	No	Expressiveness:high / medium / low ( photo_avatar + Avatar IV only); default low
engine	object	No	Engine configuration; default Avatar IV
engine.type	string	No	Engine Type:avatar_iv / avatar_v; Pass {"type":"avatar_v"} to Enable Avatar V

Response Parameters

Field	Type	Instructions
error	object / null	Error message when failed; null when successful
data.video_id	string	Video Task ID, used for the "Query Video Generation Status" API
data.status	string	Initial state of the task
data.output_format	string	Output Format

Request Example

Example A: Platform pre-set Avatar (default_voice_id has a value)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "avatar",
    "avatar_id": "lk_studio_preset_001",
    "title": "Product Introduction",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "script": "Hello, welcome to our product demo.",
    "voice_settings": {
      "speed": 1.0,
      "pitch": 1.0,
      "volume": 1.0
    }
  }'

Example B: Self-built Photo Avatar (without default_voice_id, audio must be passed in)

Looks obtained through "Create Photo Avatar" do not come with built-in voices and require explicit provision of script or audio_url:

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "avatar",
    "avatar_id": "lk_abc123def456",
    "title": "Product Introduction",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "fit": "cover",
    "background": {
      "type": "color",
      "value": "#ffffff"
    },
    "output_format": "mp4",
    "script": "Hello, welcome to our product demo.",
    "expressiveness": "medium"
  }'

Or use pre-recorded audio:

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "avatar",
    "avatar_id": "lk_abc123def456",
    "title": "Product Introduction",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio_url": "https://example.com/narration.mp3"
  }'

Response

{
  "error": null,
  "data": {
    "video_id": "vid_abc123def456",
    "status": "pending",
    "output_format": "mp4"
  }
}

---

7. Query video generation status

Query the generation progress and results based on the video_id returned from video creation.

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos/{videoId}

Request Parameters

Field	Type	Required	Instructions
endpointPath	string	is	Path parameter, model access point identifier
videoId	string	is	Path parameter, video task ID (returned when creating a video video_id)

Response Parameters

Field	Type	Instructions
error	object / null	Error message when failed; null when successful
data.id	string	Video Task ID
data.status	string	Task Status:pending / processing / completed / failed
data.title	string	Video Title
data.created_at	long	Creation Time (Unix Timestamp)
data.completed_at	long	Completion time (Unix timestamp); Returned when status=completed
data.video_url	string	Video download URL;Returned when status=completed
data.thumbnail_url	string	Thumbnail URL
data.gif_url	string	GIF Preview URL
data.captioned_video_url	string	Video URL with subtitles
data.subtitle_url	string	Subtitle File URL
data.duration	double	Video duration (seconds);Returned when status=completed
data.folder_id	string	Parent Folder ID
data.output_language	string	Output Language
data.failure_code	string	Failure error code;Returned when status=failed
data.failure_message	string	Failure reason;Returned when status=failed
data.video_page_url	string	Video Page URL

Request Example

Request

curl --request GET \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/${ENDPOINT_PATH}/heygen/videos/vid_abc123def456' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Response

{
  "error": null,
  "data": {
    "id": "vid_abc123def456",
    "status": "completed",
    "title": "Product Introduction",
    "created_at": 1717843200,
    "completed_at": 1717843500,
    "video_url": "https://resource.heygen.com/videos/xxx.mp4",
    "thumbnail_url": "https://resource.heygen.com/videos/xxx_thumb.jpg",
    "gif_url": "https://resource.heygen.com/videos/xxx.gif",
    "captioned_video_url": null,
    "subtitle_url": null,
    "duration": 12.5,
    "folder_id": null,
    "output_language": "English",
    "failure_code": null,
    "failure_message": null,
    "video_page_url": "https://app.heygen.com/videos/xxx"
  }
}