how-tos

HeyGen Avatar 6 API 文本生成数字人:无需音频文件,用脚本生成主持人视频

Poyo.ai Team
5 min read
Share:

HeyGen Avatar 6 API 文本生成数字人:用脚本生成主持人视频

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 目录中公布了全部名称。目录有五个键:

键内容
modelsheygen-avatar-6、heygen-avatar-6-turbo(同样的名称在两者上都可用)
default_voiceWarm 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 个;有八位人物只有一个形象。名称描述了场景、服装和机位,通常不用预览就能选出来:

你想要名称中找这些词示例
正对镜头的主持人FrontAbigail Office Front、Bryan Suit Front
四分之三侧角SideAbigail Office Side
坐姿、轻松随意Sofa、Sitting、LoungeAnnie Sofa Sitting Front
某种角色或场景Doctor、Nurse、Yoga、Tech ExpertAnn 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-turboAbigail Office Front / Jessica Anne Bogart27 个单词10.16 秒110 积分($0.55)约 2.4 分钟
heygen-avatar-6Bryan Tech Expert / Andrew21 个单词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 的文本请求如何计费?

按成片时长向上取整到整秒,乘以该模型的每秒费率。提交时预留积分,任务结束时结算。

Share: