HeyGen Avatar IV API 怎么用？5 分钟让照片开口说话

TL;DR

• 它是什么：HeyGen 出品的照片数字人。一张人像照片加一段台词（或一段音频），生成照片里这个人开口说话的 MP4。已在 HiAPI 上线，打开模型页 上传照片就能生成。
• 多少钱：按视频秒数计费，$0.15 一秒，720p 和 1080p 同价，10 秒一条 $1.50。
• API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 heygen-avatar-iv，传照片链接和台词，拿到 taskId 后查询，5 分钟就能跑通第一条。

先看一条成片。下面这段 9 秒的横版讲解，用的就是一张毛衣半身照加一句英文台词：

VIDEO

1080p / 16:9，9 秒，声音 Cute Chloe - Friendly。照片里的毛衣、发型和房间都保留下来，口型、眨眼和轻微点头跟着语音走。

台词原文：

Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.

用这段台词生成 → 台词已填好，上传你自己的照片就能生成。

HeyGen Avatar IV 适合谁？

手里有一张照片、想让"这个人"出镜说话，就用它。常见用法：

• 产品讲解和口播种草：同一张照片换台词，批量出不同卖点的短视频。
• 课程和培训：老师录一次照片，每节课只写讲稿。
• 企业通知和客服视频：顾问、医生、店长的形象固定，内容随时更新。
• 插画和 3D 角色：只要有清晰的人脸，卡通形象也能开口。

不需要自己的形象、想从预置数字人里挑，或者要透明背景、字幕、4K，选 HeyGen Avatar V，价格一样。

先在模型页试一次

写代码之前，先在网页上出一条，看看你的照片效果如何：

1. 点上面的"用这段台词生成"，台词会自动填好。
2. 上传一张正脸、光线均匀的单人照。
3. 选 1080p、16:9，声音可以不选，默认是 Warm Pro Narrator。
4. 点生成，完成后在线预览，满意就下载。

10 秒一条 $1.50，$10 大约能生成 66 秒视频，够你换几张照片、几种声音对比效果。

调 API 前准备三样东西

1. API Key：在 控制台 创建，格式 sk-...，放在 Authorization: Bearer 请求头里。
2. 照片的公网 HTTPS 链接：正脸、五官无遮挡、光线均匀、嘴巴自然闭合的单人照最稳。接口按链接读取照片，先把图片传到你自己的存储或 CDN。
3. 台词或音频，二选一：给台词就由所选声音朗读；给音频（audio_url）就让口型跟着你的录音走。

最小请求：cURL 版

下面的照片链接可以直接用，换上自己的 Key 就能跑：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
      "prompt": "Hi, I'\''m Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
      "voice": "Cute Chloe - Friendly",
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }
  }'

返回的任务 ID 在 data.taskId：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

时长不用传：用台词时由台词长度和语速决定，用音频时和音频一样长。

查询结果

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status 变成 success 后，在 data.output 里找 type 为 video 的那一项，url 就是 MP4：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "success",
    "model": "heygen-avatar-iv",
    "output": [
      {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4"}
    ]
  },
  "message": "success"
}

Python 完整示例：创建、轮询、下载

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "heygen-avatar-iv",
    "input": {
        "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
        "prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
        "voice": "Cute Chloe - Friendly",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(8)

if data["status"] == "success":
    video_url = next(o["url"] for o in data["output"] if o["type"] == "video")
    with open("avatar-iv.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    print("saved avatar-iv.mp4")
else:
    print(data.get("error"))

参数一览

完整的声音列表见 中文文档。

两种驱动方式和背景怎么用

台词驱动：传 prompt 和 voice，适合批量换内容。下面这条竖版口播，照片本身就是 9:16，输出画面刚好填满：

VIDEO

1080p / 9:16，8 秒，声音 Andrew。

I've been using these new earbuds for a week. The noise canceling is super quiet, and the battery lasts all day. Follow me for more.

用这段台词生成 → 台词已填好，上传你的竖版照片，选 9:16 就能生成。

音频驱动：已经录好旁白，或者要用自己的声音，就把 prompt 和 voice 换成 audio_url，口型和停顿都跟着录音走。

背景：输出画幅和照片比例不同时，画面会有留白，用 background 填上。纯色传 {"type": "color", "value": "#F5EFE6"}，图片传 {"type": "image", "value": "https://..."}。下面这条把横版老师照放进竖屏，上下用黑板图填满：

VIDEO

1080p / 9:16，11 秒，声音 Professor Dean，background 用一张黑板图。

Hello everyone. Today we'll explain the Pythagorean theorem in five minutes. In a right triangle, the squares of the two legs add up to the square of the hypotenuse.

用这段台词生成 → 台词已填好，上传你的照片就能生成。

上线前注意这 3 件事

1. 服务端用回调。 请求里加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务结束自动推送，省掉轮询。
2. 拿到 taskId 后别重复 POST。 每次 POST /v1/tasks 都会新建任务、单独计费。网络超时先查自己有没有存下 taskId，有就继续查询或等回调。
3. 成功后立刻下载。 输出链接会过期，拿到结果就把 MP4 存到自己的存储。

怎么计费？

$0.15 一秒，按生成视频的实际秒数结算，分辨率不影响价格，直接用 1080p。创建任务时按估算时长预扣，完成后按实际秒数多退少补，失败任务全额退回。

费用只和秒数有关，省钱就把台词写短。每月 300 条 10 秒口播约 $450，20 条 60 秒课程约 $180。完整价目见 定价页。

开头小林那条 9 秒视频花了 $1.35。用同一段台词生成 → 台词已填好，上传你的照片，算算自己的视频要几秒。

常见问题

能用中文台词吗？ 可以。prompt 支持中文和英文，最多 5000 个字符。

能用自己的声音吗？ 可以。把录音传给 audio_url，最长 600 秒，口型跟着你的录音走。

什么样的照片效果最好？ 正脸、五官无遮挡、光线均匀、嘴巴自然闭合的单人照。插画和 3D 角色也行，要有清晰的人脸。侧脸、戴口罩、多人合照、脸很小的照片换一张再试；识别失败的任务会全额退款。

照片是横的，想出竖版视频怎么办？ aspect_ratio 设成 9:16，再用 background 填上下留白，像上面黑板那条一样。

一条视频要多久？ 生成是异步的，台词越长、分辨率越高，等得越久。服务端用回调，结束时自动推送。

HeyGen Avatar IV 相关链接

• HeyGen Avatar IV 模型页：上传照片在线生成
• HeyGen Avatar IV 中文文档：全部参数和 102 个声音
• HeyGen Avatar V 模型页：497 个预置数字人，支持透明背景和字幕
• HiAPI 定价页：所有模型的按秒、按张价格

现在就试：找一张自己的正脸照，用小林这段台词生成 →，台词已填好，上传照片，选 1080p、16:9，一条 9 秒左右的视频 $1.35。