Points at the map with its flipper on 'kalt und klar'.
HeyGen Avatar 6 Turbo Reference Video API
heygen/avatar-6-turbo/ref-video-to-videoHeyGen Avatar 6 Turbo Reference Video API 让动画和插画角色开口说话:上传一段角色短视频和 2–60 秒语音,即可得到 1080p 或 2K 的口型同步说话视频,保留角色的画风和原视频构图。
拖拽文件、粘贴剪贴板素材,或输入 URL。 必填。动画或插画角色视频,至少 2 秒,最大 50 MB。
1/1 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选。同一角色的 1 张静帧图片。
1/1 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 必填。2–60 秒语音,最大 15 MB。
1/1 个素材
示例
REST API
快速开始
三步完成第一个 HeyGen Avatar 6 Turbo Reference Video to Video 请求。
接入 Vidgo API
创建 API Key,保存在服务端,以 Bearer Token 放在 Authorization 请求头里。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权
- Authorization: Bearer VIDGO_API_KEY
提交生成任务
运行示例请求。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "heygen/avatar-6-turbo/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He lifts the parcel on 'Parcel' and winks on 'I promise'."
}
}'等待结果
用返回的 task_id 查询,直到 finished 或 failed;成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}状态为 not_started 或 running 时约每 2 秒查询一次;finished 或 failed 时停止,成功后读取 data.files[].file_url。也可以在提交时加 callback_url 异步接收结果。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "TASK_ID",
"status": "not_started",
"created_time": "2026-11-19T08:00:00"
}
}{
"code": 200,
"data": {
"task_id": "TASK_ID",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/.../output.mp4",
"file_type": "video"
}
],
"created_time": "2026-11-19T08:00:00",
"error_message": null,
"progress": 100
}
}完整可运行示例
把提交、轮询、终态处理和取结果放在一个脚本里。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "heygen/avatar-6-turbo/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He lifts the parcel on 'Parcel' and winks on 'I promise'."
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
model 和 callback_url 放在请求根级,生成参数放在 input 里。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 固定为 heygen/avatar-6-turbo/ref-video-to-video。 |
| callback_url | string (URL) | 否 | — | 接收任务完成通知的公开 HTTP(S) 地址。 |
| input | object | 是 | — | 生成参数。 |
| input.video_url | string | 是 | — | 动画或插画角色视频的公开 HTTP(S) 地址,至少 2 秒,最大 50 MB。 |
| input.image_urls | string[] | 否 | — | 同一角色的 1 张静帧图片的公开 HTTP(S) 地址。 |
| input.audio_url | string | 是 | — | 公开 HTTP(S) 语音地址,2–60 秒,最大 15 MB。 |
| input.prompt | string | 否 | — | 手势、表情、姿态的动作提示,最多 1,200 个字符。 |
| input.resolution | string | 否 | 1080p | 1080p 或 2K。 |
响应字段
提交后立即返回任务信息;查询状态时会随进度返回进度、输出文件或失败原因。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务结果码,成功为 0 或 200。 |
| message | string | 响应或错误信息。 |
| data.task_id | string | 任务 ID,用于查询状态。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间。 |
| data.progress | number | 完成百分比(有进度时返回)。 |
| data.files[].file_url | string | 生成视频的公开地址。 |
| data.files[].file_type | string | 文件类型,此处为 video。 |
| data.error_message | string | null | 失败时的原因。 |
任务生命周期
not_started 和 running 为进行中;finished 和 failed 为终态,收到即停止轮询。
not_started任务已受理,排队等待开始。
running视频生成中,继续轮询。
finished已完成,从 data.files[].file_url 读取视频。
failed生成失败,查看 data.error_message。
轮询与错误
- 鉴权401 表示 API Key 缺失或无效,请在控制台检查。
- 参数校验400 表示参数有误,请对照上方参数表检查字段和时长。
- 轮询间隔每 2 秒查询一次,长任务可逐步延长到 5 秒。
- 终态收到 finished 或 failed 即停止轮询。
- 回调提供 callback_url,完成时自动通知。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 模型 | heygen/avatar-6-turbo/ref-video-to-video | HeyGen Avatar 6 Turbo 异步视频生成的模型 ID。 |
| 分辨率 | 1080p / 2K | 默认 1080p。 |
| 参考视频 | ≥2 秒,≤50 MB | 动画或插画角色。 |
| 音频 | 2–60 秒,≤15 MB | 有音频时视频时长跟随音频。 |
| 价格 | 每秒 10 / 18 积分 | 1080p / 2K |
HeyGen Avatar 6 Turbo Reference Video API 常见问题
HeyGen Avatar 6 Turbo Reference Video API是什么?
HeyGen Avatar 6 Turbo 是 HeyGen 于 2026 年 11 月 17 日发布的说话数字人模型。HeyGen Avatar 6 Turbo Reference Video API把卡通或插画角色的短视频和 2–60 秒语音变成口型同步的说话视频,支持 1080p 和 2K,保留角色画风。可选的同角色静帧和最多 1,200 个字符的提示词让结果更精准。调用时使用模型 ID heygen/avatar-6-turbo/ref-video-to-video,也可以在上方体验区直接试用。
HeyGen Avatar 6 Turbo Reference Video API 的这个模式支持哪些角色?
动画和插画角色:黏土动画、2D 卡通、水彩、低多边形 3D、纸艺等风格。
HeyGen Avatar 6 Turbo Reference Video API 的参考视频要多长?
至少 2 秒,最大 50 MB;输出保留视频比例。
HeyGen Avatar 6 Turbo Reference Video API 生成角色视频怎么收费?
HeyGen Avatar 6 Turbo Reference Video 价格为1080p 每秒 10 积分($0.05),2K 每秒 18 积分($0.09),按音频时长向上取整;1080p 的 5 秒台词为 50 积分($0.25)。
HeyGen Avatar 6 Turbo Reference Video API 请求里要不要加 image_urls?
视频里角色面部较小或是侧脸时,补一张同一角色的静帧,给模型清晰的参考。
如何用角色视频调用 HeyGen Avatar 6 Turbo Reference Video API?
向 https://api.vidgo.ai/api/generate/submit 发送 POST 请求,model 填 heygen/avatar-6-turbo/ref-video-to-video,带上 video_url 和 audio_url,再轮询 /api/generate/status/{task_id} 或设置 callback_url。
