![]()
这份 HeyGen Avatar 6 API 指南带你从拿到 API 密钥一直走到在 PoYo 上生成一个完整的说话视频。你只需用模型 ID heygen-avatar-6(或 heygen-avatar-6-turbo)提交一个 JSON 请求,保存返回的任务 ID,然后轮询直到 MP4 生成完毕。下面所有请求体都遵循 PoYo 文档的格式;如果想先看看有哪些输入,HeyGen Avatar 6 模型页上有 Playground。
开始之前
- 在
poyo.ai/dashboard/api-key创建密钥,并导出为POYO_API_KEY。密钥只放在服务器端。 - 把所有输入文件托管在公开、可直接下载的 HTTP 或 HTTPS URL 上。PoYo 会自己去拉取媒体,不接受在请求中直接上传。
- 选择档位。两个 ID 接受相同的字段。Turbo 在 1080p 下每秒 10 积分($0.05);Avatar 6 每秒 20 积分($0.10)。参见 Avatar 6 vs Turbo。
用 cURL 发出第一个 HeyGen Avatar 6 API 请求
最快的第一个请求完全不需要媒体文件:由 HeyGen 公共数字人朗读你的文本。
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "heygen-avatar-6-turbo",
"input": {
"avatar": "Abigail Office Front",
"text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
"voice": "Warm Pro Narrator",
"prompt": "Speak with calm confidence and nod slightly at the end.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}'
成功的响应包含 "code": 200 和 data.task_id,status 为 not_started。这表示任务已排队,而不是视频已生成。接着轮询:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
状态有 not_started、running、finished 和 failed。状态为 finished 时,MP4 位于 data.files[] 中 file_type 为 video 的条目,data.credits_amount 显示扣费金额。状态为 failed 时,读取 data.error_message。
有上限的 Python 轮询循环
在 2026 年 11 月 19 日的上线当天测试中,短文本片段从提交到出结果大约需要 2 到 2.4 分钟。下面的循环每 5 秒轮询一次(状态文档建议 2–5 秒),15 分钟后停止,并且超时后绝不重新提交,因为第二次提交就是第二个计费任务。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
return body["data"]
def generate(payload, timeout_s=900):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
print("task", task_id, flush=True)
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
return videos[0], task.get("credits_amount")
raise TimeoutError("still running; poll this task again later: " + task_id)
url, credits = generate({
"model": "heygen-avatar-6",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p",
},
})
print(url, credits)
生产环境中,请在顶层添加 callback_url 来代替轮询。任务变为 finished 或 failed 时,PoYo 会 POST 同样的任务对象(不带 code / data 外层包装),并在 X-Webhook-Signature 中附带 HMAC-SHA256 签名;签名规则见 Webhook 文档。
HeyGen Avatar 6 API 的三种输入模式
没有模式开关。有 avatar 就是公共数字人模式;否则有 video_url 就是参考视频模式;否则按照片模式运行。每个请求只使用一种模式的输入。
公共数字人 + 文本模式
见上文示例。avatar 是 1,248 个公共形象之一,text 最多 1,000 个字符,voice 是 102 个音色之一(默认 Warm Pro Narrator)。如何从目录中挑选形象和音色,见文本生成数字人教程。
公共数字人 + 自有音频模式
把 text 和 voice 换成 audio_url。aspect_ratio 仍然有效:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
照片模式
一张真人照片加语音。视频保持照片的宽高比,所以发送前先把照片裁成你想要的画幅。callback_url 与 model 同级,不放在 input 里面:
{
"model": "heygen-avatar-6",
"callback_url": "https://your-domain.com/callback",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p"
}
}
参考视频模式
适用于动画或插画角色。video_url 是该角色的一段视频;image_urls 可选地再加一张同一角色的静态图。输出保持视频片段的宽高比:
{
"model": "heygen-avatar-6-turbo",
"input": {
"video_url": "https://example.com/cartoon-character.mp4",
"image_urls": ["https://example.com/cartoon-character.png"],
"audio_url": "https://example.com/speech.mp3",
"resolution": "2K"
}
}
HeyGen Avatar 6 API 字段校验规则
提交前请在自己的代码中检查这些规则;它们都是文档中写明的限制。
| 字段 | 模式 | 规则 |
|---|---|---|
model | 全部 | heygen-avatar-6 或 heygen-avatar-6-turbo |
image_urls | 照片(必填)、参考视频(可选) | 恰好包含一个 URL 的数组 |
video_url | 参考视频 | 至少 2 秒,最大 50 MB |
avatar | 公共数字人 | 列出的 1,248 个名称之一 |
audio_url | 照片、参考视频;或在公共数字人中替代 text | 2–60 秒,最大 15 MB |
text | 公共数字人 | 1–1,000 个字符 |
voice | 使用 text 的公共数字人 | 102 个名称之一 |
prompt | 全部 | 最多 1,200 个字符 |
aspect_ratio | 公共数字人 | 16:9、9:16、1:1、4:5、5:4 |
resolution | 全部 | 1080p(默认)或 2K |
数字人和音色名称匹配时不区分大小写、忽略多余空格,但文档注明了一个例外:Hope 和 Hope (末尾带空格)是两个不同的音色。输入 schema 不允许额外字段,所以不要发送 HeyGen 自家 API 中的原生选项,例如 motion_expressiveness 或 motion_prompt;在 PoYo 上,动作指令写在 prompt 里。
需要处理的错误
务必读取响应体中的 code。部分校验错误会以 HTTP 200 加 "code": 400 的形式返回,只检查 HTTP 状态码是不够的。
响应体 code | error.type | 处理方式 |
|---|---|---|
| 400 | validation_error 等 | 修正输入:音频不在 2–60 秒内、数字人名称不存在、混入了其他模式的字段。不要原样重试 |
| 401 | authentication_error | 检查 Authorization: Bearer 请求头 |
| 402 | insufficient_credits_error | 充值,或等待运行中的文本任务结算(见下文) |
| 429 | rate_limit_error | 退避后重试 |
| 500 / 502 / 503 | internal_error、upstream_error、service_error | 指数退避重试 |
音频时长、参考视频时长和数字人名称在提交时就会检查,所以这类错误会立即返回 400,而不是几分钟后任务失败。
402 有一个 HeyGen 特有的坑。在上线当天的测试中,提交了两个文本任务之后,第三个请求(Turbo,2K,22 个单词)返回 HTTP 200,响应体 code 为 402,类型为 insufficient_credits_error:"this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." 文本任务在运行期间会占用积分,所以即使最终费用在余额之内,连续提交文本任务也可能触发 402。请把文本任务排队处理,或者直接把错误信息展示给用户,因为它已经写明了两个数字。
第一笔 HeyGen Avatar 6 API 账单如何计算
PoYo 按输出秒数计费,向上取整到整秒(1 积分 = $0.005):
| 模型 | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 积分($0.05)/ 秒 | 18 积分($0.09)/ 秒 |
heygen-avatar-6 | 20 积分($0.10)/ 秒 | 29 积分($0.145)/ 秒 |
- 使用
audio_url(所有模式):按音频时长向上取整计费,在提交时扣除。Avatar 6 1080p 下一段 12.3 秒的音频为 13 × 20 = 260 积分($1.30)。 - 使用
text:提交时预留积分,任务结束时按成片时长结算。在我们的测试中,Turbo 上 27 个单词的脚本生成了 10.16 秒视频,按 11 秒计费,按当前价格为 110 积分(11 秒 × 10,$0.55);Avatar 6 上 21 个单词的脚本生成了 6.88 秒视频,按 7 秒计费,按当前价格为 140 积分(7 秒 × 20,$0.70)。
对账时以已完成任务的 data.credits_amount 为准。更多示例见 HeyGen Avatar 6 API 价格。
常见问题
如何用 Python 调用 HeyGen Avatar 6 API?
用 requests 向 https://api.poyo.ai/api/generate/submit POST JSON,然后像上面的循环那样,带截止时间轮询 /api/generate/status/{task_id}。任何 HTTP 客户端都可以,不强制使用 SDK。
HeyGen Avatar 6 API 有回调吗?
有。在请求顶层添加 callback_url。任务完成或失败时,PoYo 会 POST 任务数据。
为什么我的 HeyGen Avatar 6 API 请求返回了 HTTP 200 却没有任务?
请读取响应体。只要 code 不是 200,即使 HTTP 状态是 200,请求也已失败;原因见 error.message。
可以直接向 HeyGen Avatar 6 API 上传文件吗?
不可以。image_urls、video_url 和 audio_url 接受的是公开的 HTTP 或 HTTPS URL,由 PoYo 下载。
HeyGen Avatar 6 API 的结果保留多久?
生成的视频在创建后 3 天内可访问。请把 MP4 下载到你自己的存储中。