![]()
HeyGen Avatar 6 API 只需一份脚本就能生成主持人视频。在公共数字人模式下,你指定 HeyGen 1,248 个现成形象之一,发送最多 1,000 个字符的 text,再从 102 个音色中选一个,heygen-avatar-6(或 heygen-avatar-6-turbo)就会返回一个口型同步的 MP4。不需要照片,不需要录音,你这边也不需要文本转语音步骤。本教程介绍如何从目录中选择形象和音色、如何用 prompt 指导手势、如何选择画幅,以及文本请求的费用。你也可以在 HeyGen Avatar 6 模型页上浏览这些形象。
文本生成数字人请求
以下是文档中公共数字人 + 文本模式的请求体:
{
"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"
}
}
| 字段 | 必填 | 规则 |
|---|---|---|
avatar | 是 | 1,248 个形象名称之一 |
text | 是(替代 audio_url) | 1–1,000 个字符 |
voice | 否 | 102 个名称之一;默认 Warm Pro Narrator |
prompt | 否 | 最多 1,200 个字符的导演指令 |
aspect_ratio | 否 | 16:9(默认)、9:16、1:1、4:5、5:4 |
resolution | 否 | 1080p(默认)或 2K |
选中这个模式的依据是 avatar 的存在。不要同时发送 image_urls 或 video_url;每个请求只使用一种模式的输入。提交到 POST https://api.poyo.ai/api/generate/submit,并像 HeyGen Avatar 6 API 指南中那样轮询 /api/generate/status/{task_id}。
从目录中选择数字人形象
PoYo 在 Avatars and Voices 页面和 JSON 目录中公布了全部名称。目录有五个键:
| 键 | 内容 |
|---|---|
models | heygen-avatar-6、heygen-avatar-6-turbo(同样的名称在两者上都可用) |
default_voice | Warm Pro Narrator |
avatars | 全部 1,248 个形象名称,平铺列表 |
avatars_by_person | 同样的形象按 156 位人物分组 |
voices | 全部 102 个音色名称 |
每位人物有一个或多个形象,每个形象都是一个独立的 avatar 值。Abigail 有五个(Abigail (Upper Body)、Abigail Office Front、Abigail Office Side、Abigail Sofa Front、Abigail Sofa Side);Annie 有 54 个;有八位人物只有一个形象。名称描述了场景、服装和机位,通常不用预览就能选出来:
| 你想要 | 名称中找这些词 | 示例 |
|---|---|---|
| 正对镜头的主持人 | Front | Abigail Office Front、Bryan Suit Front |
| 四分之三侧角 | Side | Abigail Office Side |
| 坐姿、轻松随意 | Sofa、Sitting、Lounge | Annie Sofa Sitting Front |
| 某种角色或场景 | Doctor、Nurse、Yoga、Tech Expert | Ann Doctor Standing、Adriana Nurse Front、Amelia Yoga Front、Bryan Tech Expert |
大约 480 个名称包含 Front,大约 430 个包含 Side。做系列讲解视频时,选定一位人物并只用其 Front 形象,这样各期视频的主持人保持一致;穿插镜头可以用对应的 Side 形象。
名称匹配不区分大小写并忽略多余空格,所以 abigail office front 会选中 Abigail Office Front。PoYo 在提交时会把 avatar 与列表比对,所以拼写错误会立即返回 400,而不是任务失败。先在自己的代码中校验:
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
音色校验特意使用精确名称,原因见下一节。
选择音色
voice 决定由谁来朗读 text。省略时使用 Warm Pro Narrator。102 个音色中有普通人名(Andrew、Ivy、Jessica Anne Bogart)、描述性名称(Calm Chloe、Professor Dean、Radio Rick、Chill Brian),也有一些名称中带风格标签。
有三点容易出错:
- 末尾空格可能有意义。 文档特别指出
Hope和Hope(末尾带空格)是两个不同的音色。Archer、Cassidy、Adam Stone、Spuds Oxley和Andrew Rizz在目录中也以空格结尾。请从 JSON 中复制名称,不要手动重新输入。 - 有些名称包含表情符号或类似文件名的后缀,例如
Cute Chloe - Friendly 😊或Brenda - UGC - 1.mp4。这些字符都是名称的一部分。以 UTF-8 JSON 发送请求体,名称就会原样传递。 - 音色与数字人不绑定。 102 个音色中的任何一个都可以为 1,248 个形象中的任何一个朗读。选一个适合画面中人物的音色;我们上线当天的测试把
Bryan Tech Expert与Andrew搭配,把Abigail Office Front与Jessica Anne Bogart搭配。
voice 只在发送 text 时生效。如果改为发送 audio_url,数字人会说出你的录音,voice 不会被使用。
用 prompt 指导手势
prompt 接受最多 1,200 个字符的指令,用于指导手势、表情和姿态。HeyGen 的技术报告这样描述这种技巧:“把动作写在台词旁边,Avatar 6 会在对应时刻准确做出。”其示例是:“友善的药剂师。说到 'Hello' 时竖起大拇指。说到 'the counter on the left' 时用食指指向一侧。”
按照这种格式写的一个示例:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
让提示词更有效的技巧:
- 引用
text中每个动作要对应的确切词语,让触发点毫不含糊。 - 先描述一个角色或情绪(“Friendly product expert”),再写触发点。
- 没有具体触发点时就省略
prompt。HeyGen 的 Avatar 6 发布页称,模型会自行“让手势、情绪和表情与你的脚本相匹配”。
按投放位置选择宽高比
aspect_ratio 只存在于公共数字人模式;照片模式和参考视频模式保持输入的画幅。
| 投放位置 | aspect_ratio |
|---|---|
| 网站、YouTube、LMS 课程 | 16:9(默认) |
| Shorts、Reels、TikTok、快拍 | 9:16 |
| 方形信息流帖子、应用内卡片 | 1:1 |
| 竖版信息流帖子 | 4:5 |
| 横版信息流帖子 | 5:4 |
resolution 是独立设置:任何比例下都可选 1080p 或 2K。2K 每秒更贵,所以草稿用 1080p 渲染。
视频时长与费用
使用文本时,视频时长取决于数字人读完文本所需的时间,最多 1,000 个字符。计费按成片时长向上取整到整秒。提交时预留积分,任务完成时按实际秒数结算。
我们于 2026 年 11 月 19 日在生产 API 上的上线当天测试(16:9,1080p):
| 模型 | 数字人 / 音色 | 脚本 | 输出 | 费用(按当前价格) | 耗时 |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 个单词 | 10.16 秒 | 110 积分($0.55) | 约 2.4 分钟 |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 个单词 | 6.88 秒 | 140 积分($0.70) | 约 2 分钟 |
在这两次运行中,语速约为每秒 2.7 和 3.1 个单词,可用于粗略估算预算,但不能作为保证,因为节奏因音色和脚本而异。每秒费率:Turbo 在 1080p 下 10 积分($0.05),2K 下 18($0.09);Avatar 6 为 20 积分($0.10)或 29($0.145)。更多内容见 HeyGen Avatar 6 API 价格。
由于文本任务运行时会占用预留额度,一次性提交很多可能会返回 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." 请把文本任务排队,或保持足以覆盖进行中预留额度的余额。迭代阶段用 Turbo;何时切换见 Avatar 6 vs Turbo 对比。
常见问题
HeyGen Avatar 6 API 能把文本变成数字人说话视频吗?
可以。在公共数字人模式下,发送 avatar、最多 1,000 个字符的 text,以及可选的 voice。不需要音频文件。
HeyGen Avatar 6 API 的数字人和音色列表在哪里?
在 PoYo 文档的 Avatars and Voices 页面,以及一个可下载的 JSON 目录中,目录包含 avatars、avatars_by_person 和 voices 键。
HeyGen Avatar 6 API 的默认音色是什么?
Warm Pro Narrator,在省略 voice 时使用。
能用我自己的照片配合文本,而不是现成数字人吗?
不能。text 只在公共数字人模式下可用。如果要用自己的照片,请使用照片模式,配合 image_urls 和 audio_url;如有需要,先用 TTS 模型生成音频。
HeyGen Avatar 6 文本生成数字人支持哪些宽高比?
16:9、9:16、1:1、4:5 和 5:4,分辨率为 1080p 或 2K。
HeyGen Avatar 6 API 的文本请求如何计费?
按成片时长向上取整到整秒,乘以该模型的每秒费率。提交时预留积分,任务结束时结算。