MaaS_HG_video_translate_v3

获取支持的翻译语言

请求URL

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

请求参数

无

响应参数

字段	类型	说明
data.languages	string[]	支持的目标语言名称列表，如 "Chinese (Simplified)"、"Spanish"
error	string	请求失败时显示错误信息；请求成功时显示 null

请求示例

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"]
  }
}

---

上传素材

请求URL

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

请求参数

Content-Type: multipart/form-data

字段	类型	必填	说明
file	binary	是	要上传的文件，最大 32 MB，支持 png / jpeg / mp4 / webm / mp3 / wav / pdf

响应参数

字段	类型	说明
error	string	请求失败时显示错误信息；请求成功时显示 null
code	integer	状态码，100 表示成功
data.asset_id	string	素材唯一 ID；创建翻译任务时填入 video.asset_id（type="asset_id"）
data.url	string	素材访问 URL
data.mime_type	string	MIME 类型，如 video/mp4
data.size_bytes	long	文件大小（字节）
message	string	结果说明

请求示例

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

---

创建视频翻译任务

异步接口：调用后返回子任务 ID 列表，通过「3.6 查询视频翻译状态」轮询直到 status 变为 success。支持一次指定多个目标语言，每个语言生成独立的 video_translation_id。

请求URL

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

请求参数

字段	类型	必填	说明
video	object	是	视频来源，二选一格式（见下方说明）
video.type	string	是	"url" 或 "asset_id"
video.url	string	条件必填	type="url" 时填写；支持直链、Google Drive、YouTube
video.asset_id	string	条件必填	type="asset_id" 时填写；使用 POST /v3/assets 上传后返回的 asset_id
output_languages	string[]	是	目标语言列表，如 ["Chinese (Simplified)", "Spanish"]；每个语言生成一个独立子任务
input_language	string	否	源语言；不传则自动检测
title	string	否	视频标题（HeyGen 后台展示用）
translate_audio_only	boolean	否	true：仅翻译音轨，不做唇形同步（适用于发言者不可见的视频）；默认 false
speaker_num	integer	否	视频中发言者数量
mode	string	否	翻译质量：speed（默认，快速）/ precision（高精度，耗时更长）
enable_dynamic_duration	boolean	否	动态时长调整，增强不同语速语言间的流畅度；默认 false
keep_the_same_format	boolean	否	保持与输入视频相同的输出格式；默认 false
enable_caption	boolean	否	是否生成字幕文件；默认 false
disable_music_track	boolean	否	去除背景音乐；默认 false
enable_speech_enhancement	boolean	否	语音增强；默认 false

响应参数

字段	类型	说明
error	string	请求失败时显示错误信息；请求成功时显示 null
code	integer	状态码，100 表示成功
data.video_translation_ids	string[]	子任务 ID 列表，每个目标语言对应一个；通过 3.6 接口查询各子任务的具体语言和状态
message	string	结果说明

请求示例

Request（URL 形式）

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（asset_id 形式）

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

---

查询视频翻译状态

异步接口：轮询此接口直到 data.status 变为 success。每个 video_translation_id 需单独查询。

请求URL

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

请求参数

字段	类型	必填	说明
id	string（路径参数）	是	视频翻译子任务 ID（video_translation_id）

响应参数

字段	类型	说明
error	string	请求失败时显示错误信息；请求成功时显示 null
data.id	string	翻译任务 ID
data.status	string	任务状态：pending / running / completed / failed
data.output_language	string	目标语言
data.input_language	string	源语言（自动检测或指定）
data.duration	float	视频时长（秒）；status=completed 时返回
data.translate_audio_only	boolean	是否仅翻译音轨
data.video_url	string	翻译完成后的视频下载 URL；status=completed 时返回
data.audio_url	string	翻译完成后的音频下载 URL；status=completed 时返回
data.srt_caption_url	string	SRT 字幕下载 URL；enable_caption=true 且 completed 时返回
data.vtt_caption_url	string	VTT 字幕下载 URL；enable_caption=true 且 completed 时返回
data.title	string	视频标题
data.failure_message	string	失败原因描述；status=failed 时返回
data.created_at	integer	创建时间（Unix 时间戳）

请求示例

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（处理中）

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

Response（已完成）

{
  "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（失败）

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

MaaS_HG_Video_Generation_Avatar IV

数字人使用指南

推荐按以下流程使用 Avatar 相关接口：

1. 获取 avatar_id（Look ID）

2. 调用「创建 Photo Avatar」接口新建数字人；或

3. 调用「列出 Avatar 外观」/「获取单个 Avatar 外观」接口，从返回的 data[].id（或 data.id）取得已有 Look 的 ID。

4. 判断该 avatar_id 是否自带音频信息

5. 查看 Look 详情中的 default_voice_id 字段：

   • 有值（常见于平台预置的 studio_avatar 等）：Avatar 已绑定默认语音。创建视频时只需传 script（口播文本）即可，无需 audio_url / audio_asset_id 等预录音频字段。

   • 为空/null（通过「创建 Photo Avatar」新建的 photo_avatar 一定属于此类）：Avatar 不自带语音信息，创建视频时必须额外提供音频入参——script 与 audio_url / audio_asset_id 二选一，不可全部省略。

---

1. 列出 Avatar 分组

请求 URL

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

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
ownership	string	否	归属筛选
limit	integer	否	每页返回数量
token	string	否	分页游标，用于获取下一页

响应参数

字段	类型	说明
data	array	Avatar 分组列表
data[].id	string	分组 ID
data[].name	string	分组名称
data[].created_at	long	创建时间（Unix 时间戳，毫秒）
data[].looks_count	integer	该分组下的 Look 数量
data[].preview_image_url	string	预览图 URL
data[].preview_video_url	string	预览视频 URL
data[].gender	string	性别
data[].default_voice_id	string	默认语音 ID
data[].consent_status	string	授权状态
data[].status	string	训练状态（仅私有 Avatar）：processing / pending_consent / failed / completed
data[].error	object	错误信息（若有）
data[].error.code	string	错误码
data[].error.message	string	错误描述
has_more	boolean	是否还有下一页
next_token	string	下一页分页游标

请求示例

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. 创建 Photo Avatar

请求 URL

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

Content-Type：application/json

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
type	string	是	固定值 photo
name	string	否	Avatar 名称
file	object	是	图片资产，支持 url / asset_id / base64 三种方式
file.type	string	是	输入方式：url / asset_id / base64
file.url	string	条件必填	当 file.type=url 时必填；公开可访问的 HTTPS 图片地址
file.asset_id	string	条件必填	当 file.type=asset_id 时必填；HeyGen 资产 ID
file.media_type	string	条件必填	当 file.type=base64 时必填；MIME 类型，如 image/png
file.data	string	条件必填	当 file.type=base64 时必填；base64 编码内容
avatar_group_id	string	否	归属的 Avatar Group ID；不传则自动新建分组

响应参数

字段	类型	说明
error	object / null	失败时的错误信息；成功时为 null
data.avatar_item	object	创建的 Avatar Look 信息
data.avatar_item.id	string	Look ID（前缀 lk_），创建视频时作为 avatar_id 传入
data.avatar_item.name	string	Look 名称
data.avatar_item.avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data.avatar_item.group_id	string	所属分组 ID
data.avatar_item.preview_image_url	string	预览图 URL
data.avatar_item.preview_video_url	string	预览视频 URL
data.avatar_item.gender	string	性别
data.avatar_item.tags	array	标签列表
data.avatar_item.tags[]	string	标签
data.avatar_item.default_voice_id	string	默认语音 ID
data.avatar_item.supported_api_engines	array	支持的引擎版本，如 ["avatar_v", "avatar_iv"]
data.avatar_item.supported_api_engines[]	string	引擎版本
data.avatar_item.image_width	integer	图片宽度（像素）
data.avatar_item.image_height	integer	图片高度（像素）
data.avatar_item.preferred_orientation	string	推荐方向：portrait / landscape / square
data.avatar_item.status	string	训练状态（仅私有 Avatar）
data.avatar_item.error	object	错误信息（若有）
data.avatar_group	object	归属的 Avatar Group 信息
data.avatar_group.id	string	分组 ID
data.avatar_group.name	string	分组名称
data.avatar_group.created_at	long	创建时间（Unix 时间戳，毫秒）
data.avatar_group.looks_count	integer	Look 数量
data.avatar_group.preview_image_url	string	预览图 URL
data.avatar_group.preview_video_url	string	预览视频 URL
data.avatar_group.gender	string	性别
data.avatar_group.default_voice_id	string	默认语音 ID
data.avatar_group.consent_status	string	授权状态
data.avatar_group.status	string	训练状态（仅私有 Avatar）
data.avatar_group.error	object	错误信息（若有）

请求示例

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. 列出 Avatar 外观（Looks）

请求 URL

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

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
group_id	string	否	按 Avatar Group ID 筛选
avatar_type	string	否	按 Avatar 类型筛选：studio_avatar / digital_twin / photo_avatar
ownership	string	否	归属筛选
limit	integer	否	每页返回数量
token	string	否	分页游标，用于获取下一页

响应参数

字段	类型	说明
data	array	Avatar Look 列表
data[].id	string	Look ID（前缀 lk_），创建视频时作为 avatar_id 传入
data[].name	string	Look 名称
data[].avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data[].group_id	string	所属分组 ID
data[].preview_image_url	string	预览图 URL
data[].preview_video_url	string	预览视频 URL
data[].gender	string	性别
data[].tags	array	标签列表
data[].tags[]	string	标签
data[].default_voice_id	string	默认语音 ID
data[].supported_api_engines	array	支持的引擎版本
data[].supported_api_engines[]	string	引擎版本，如 avatar_v、avatar_iv
data[].image_width	integer	图片宽度（像素）
data[].image_height	integer	图片高度（像素）
data[].preferred_orientation	string	推荐方向：portrait / landscape / square
data[].status	string	训练状态（仅私有 Avatar）
data[].error	object	错误信息（若有）
has_more	boolean	是否还有下一页
next_token	string	下一页分页游标

请求示例

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. 获取单个 Avatar 外观

请求 URL

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

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
lookId	string	是	路径参数，Avatar Look ID

响应参数

字段	类型	说明
error	object / null	失败时的错误信息；成功时为 null
data.id	string	Look ID（前缀 lk_），创建视频时作为 avatar_id 传入
data.name	string	Look 名称
data.avatar_type	string	类型：studio_avatar / digital_twin / photo_avatar
data.group_id	string	所属分组 ID
data.preview_image_url	string	预览图 URL
data.preview_video_url	string	预览视频 URL
data.gender	string	性别
data.tags	array	标签列表
data.tags[]	string	标签
data.default_voice_id	string	默认语音 ID
data.supported_api_engines	array	支持的引擎版本
data.supported_api_engines[]	string	引擎版本
data.image_width	integer	图片宽度（像素）
data.image_height	integer	图片高度（像素）
data.preferred_orientation	string	推荐方向：portrait / landscape / square
data.status	string	训练状态（仅私有 Avatar）
data.error	object	错误信息（若有）

请求示例

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. 获取单个 Avatar 分组

请求 URL

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

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
groupId	string	是	路径参数，Avatar Group ID

响应参数

字段	类型	说明
error	object / null	失败时的错误信息；成功时为 null
data.id	string	分组 ID
data.name	string	分组名称
data.created_at	long	创建时间（Unix 时间戳，毫秒）
data.looks_count	integer	该分组下的 Look 数量
data.preview_image_url	string	预览图 URL
data.preview_video_url	string	预览视频 URL
data.gender	string	性别
data.default_voice_id	string	默认语音 ID
data.consent_status	string	授权状态
data.status	string	训练状态（仅私有 Avatar）：processing / pending_consent / failed / completed
data.error	object	错误信息（若有）
data.error.code	string	错误码
data.error.message	string	错误描述

请求示例

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. 创建 Avatar 视频

异步任务接口；创建成功后返回 video_id，通过「查询视频生成状态」接口轮询结果。

音频说明

通过「创建 Photo Avatar」接口得到的 avatar_id（Look ID）不自带音频/语音信息（响应中 default_voice_id 为空）。使用该 ID 创建视频时，必须在请求体中提供以下音频字段之一：

方式	字段	说明
TTS 文本驱动	script	传入口播文本，由系统合成语音；可配合 voice_settings 调整语速/音调/音量
预录音频 URL	audio_url	传入可公开访问的音频文件 URL
预录音频资产	audio_asset_id	传入 HeyGen 资产 ID（需先上传音频素材）

script 与 audio_url 互斥，不可同时传入。

若 avatar_id 来自 List/Look 详情且 default_voice_id 有值（平台预置 Avatar 等），创建视频时传 script 即可，无需 audio_url / audio_asset_id；若 default_voice_id 为空，则须按上表提供 script 或预录音频字段。

请求 URL

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

Content-Type：application/json

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
type	string	是	固定值 avatar
avatar_id	string	是	Look ID，来自「创建 Photo Avatar」、「列出 Avatar 外观」或「获取单个 Avatar 外观」的 id 字段
title	string	否	视频标题
resolution	string	否	分辨率：4k / 1080p / 720p
aspect_ratio	string	否	宽高比：16:9 / 9:16
fit	string	否	画面适配方式：contain / cover
background	object	否	背景设置
background.type	string	否	背景类型：color / image
background.value	string	条件必填	当 background.type=color 时填写；十六进制颜色值，如 #ffffff
background.url	string	条件必填	当 background.type=image 时填写；图片 URL（与 asset_id 二选一）
background.asset_id	string	条件必填	当 background.type=image 时填写；HeyGen 资产 ID（与 url 二选一）
remove_background	boolean	否	是否去除背景
callback_url	string	否	任务完成回调 URL
callback_id	string	否	客户端自定义回调 ID
output_format	string	否	输出格式：mp4 / webm；默认 mp4
script	string	条件必填	TTS 口播文本，与 audio_url 互斥。default_voice_id 为空时（含「创建 Photo Avatar」得到的 ID）必填
audio_url	string	条件必填	预录音频 URL，与 script 互斥。default_voice_id 为空时（含「创建 Photo Avatar」得到的 ID）必填（与 script 二选一）
audio_asset_id	string	条件必填	预录音频资产 ID；与 script 二选一，适用于已上传音频素材的场景。default_voice_id 为空时须与 script / audio_url 择一提供
voice_settings	object	否	语音参数；配合 script 使用，可调整语速/音调/音量
voice_settings.speed	double	否	语速
voice_settings.pitch	double	否	音调
voice_settings.volume	double	否	音量
motion_prompt	string	否	控制 Avatar 肢体动作（photo_avatar + Avatar IV 专用）
expressiveness	string	否	表现力：high / medium / low（photo_avatar + Avatar IV 专用）；默认 low
engine	object	否	引擎配置；默认 Avatar IV
engine.type	string	否	引擎类型：avatar_iv / avatar_v；传 {"type":"avatar_v"} 启用 Avatar V

响应参数

字段	类型	说明
error	object / null	失败时的错误信息；成功时为 null
data.video_id	string	视频任务 ID，用于「查询视频生成状态」接口
data.status	string	任务初始状态
data.output_format	string	输出格式

请求示例

示例 A：平台预置 Avatar（default_voice_id 有值）

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

示例 B：自建 Photo Avatar（无 default_voice_id，须传入音频）

通过「创建 Photo Avatar」得到的 Look 不自带语音，需显式提供 script 或 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"
  }'

或使用预录音频：

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. 查询视频生成状态

根据创建视频返回的 video_id 查询生成进度与结果。

请求 URL

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

请求参数

字段	类型	必填	说明
endpointPath	string	是	路径参数，模型接入点标识
videoId	string	是	路径参数，视频任务 ID（创建视频时返回的 video_id）

响应参数

字段	类型	说明
error	object / null	失败时的错误信息；成功时为 null
data.id	string	视频任务 ID
data.status	string	任务状态：pending / processing / completed / failed
data.title	string	视频标题
data.created_at	long	创建时间（Unix 时间戳）
data.completed_at	long	完成时间（Unix 时间戳）；status=completed 时返回
data.video_url	string	视频下载 URL；status=completed 时返回
data.thumbnail_url	string	缩略图 URL
data.gif_url	string	GIF 预览 URL
data.captioned_video_url	string	带字幕的视频 URL
data.subtitle_url	string	字幕文件 URL
data.duration	double	视频时长（秒）；status=completed 时返回
data.folder_id	string	所属文件夹 ID
data.output_language	string	输出语言
data.failure_code	string	失败错误码；status=failed 时返回
data.failure_message	string	失败原因；status=failed 时返回
data.video_page_url	string	视频页面 URL

请求示例

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