使用指南
通过 HiAPI API 使用 heygen-avatar-iv 生成短视频:开发者指南
数字人和音频输入、脚本节奏、宽高比和时长,以及批量生成——附可运行的 HiAPI 请求
本页内容
为什么短视频选择 heygen-avatar-iv
短视频已成为产品发布、版本更新公告、文档讲解和社交媒体短片的默认分发渠道。对大多数工程团队而言,瓶颈不在剪辑——而在于稳定地产出真人出镜口播素材,既不用预约摄影棚,也不用与真人主播来回寄送素材。
这正是数字人视频生成要填补的空白。你提供视觉形象和音频/声音来源,模型便返回该数字人朗读脚本的渲染片段。heygen-avatar-iv 是 HiAPI 目录中面向这一工作流的端点:以竖屏优先的短片段,由主播直视镜头讲话。
该模型适用于以下场景:
- 你需要规模化产出。 同一条公告的十个本地化版本,或每次发布一条每日片段,这是一套循环,而非一次拍摄。
- 内容由脚本驱动。 如果信息就在文字里,数字人主播就足够了。
- 你希望可复现。 一次请求就是一个文件,可以对比差异、版本化并重新运行——这与录制会话不同。
- 你已在调用 API。 一次 HTTP 调用即可接入既有流水线,无需引入带独立 UI 的新工具。
它不适合即兴的、大幅手势的表演,也不适合以特定人物的物理在场为卖点的场景。把 heygen-avatar-iv 当作渲染器:给定相同输入,应得到同一类输出,这正是它可脚本化的原因。
本指南其余部分从单次测试调用讲到批量循环,包含可运行的 curl 和 Python,你可自行适配。模型详情和参数见heygen-avatar-iv 模型页。

heygen-avatar-iv 请求的构成
在编写生成代码之前,把请求建模为两个独立的输入组。几乎所有的早期 bug 都源于混淆二者。
第一组:视觉形象
这是谁出镜——决定主播面部、构图和整体外观的数字人选择。在一个营销活动中保持该组稳定。如果你要制作关于同一产品的五个片段,它们应共用同一个形象块,让系列看起来是同一位主播。
第二组:音频和声音
这是说什么以及怎么说。根据请求不同,音频来源可能是朗读你脚本文本的音色选择,也可能是提供的音轨。该组每个片段都变化:新脚本、新节奏,有时为本地化更换新音色。
它们如何映射到调用
HiAPI 请求将两个组放在同一个负载中发送到生成端点。概念上:
request
├── avatar / identity block → 在一个系列中保持稳定
└── audio / voice block → 每个片段变化
└── 脚本文本或音频来源
这种拆分引出两条实用规则:
- 参数化音频组,冻结形象组。 在代码中,将形象保持为模块级常量,将脚本和音色作为函数参数传入。这样从结构上确保一个系列的视觉一致性。
- 调试时一次只改一组。 如果片段看起来不对,只替换形象;如果听起来不对,只替换音频组。在付费渲染调用上做双变量调试代价高昂。
还要尽早确定你的音频组是文本驱动还是音轨驱动,因为这一选择会决定下一节的节奏——提供的音轨决定时序,而生成的语音则遵循你的脚本。
确切的字段名、可接受的值和默认值列在模型页上;读一遍并把它们固定在一个配置对象里,而不是把字面量散落到代码各处。

用 curl 发起你的首次调用
从一条短片段开始。这次调用的目标不是输出质量——而是端到端验证凭证、负载形状和下载路径,然后再做任何自动化。
将密钥设为环境变量,使其永远不会以明文进入 shell 历史记录:
export HIAPI_API_KEY="your_key_here"
然后发送一个最小请求。替换为你自己的数字人选择和一行简短脚本:
curl -X POST "https://api.hiapi.ai/v1/generate" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "heygen-avatar-iv",
"input": {
"avatar": "<avatar_identifier>",
"script": "这是数字人流水线的三十秒测试。如果你能在屏幕上读到这句话,说明请求形状是正确的。",
"voice": "<voice_identifier>",
"aspect_ratio": "9:16",
"duration": 30
}
}'
按顺序检查:
- 认证。 此处凭证报错意味着停止——下游一切都不重要。
- 负载校验。 模式错误会指出有问题的字段。一次只修一个字段。
- 任务受理。 调用成功会返回 job 或 task 引用,不一定是成品文件。生成是异步的;记录该标识符。
- 获取结果。 按模型页上的响应契约,用返回的引用轮询状态或获取结果 URL。
- 播放。 下载片段并观看。确认构图、方向和朗读内容与脚本一致。
将此 curl 命令保存在一个草稿文件中,填入你的真实标识符。它将成为你的对照实验:当 Python 版本出问题时,再跑一次 curl 来证明问题出在你的代码还是输入。

转向 Python 实现可重复生成
curl 调用成功后,将其封装为函数。重点不是为抽象而抽象——而是让每个参数都成为显式参数,使片段完全由调用点描述。
import os
import requests
API_URL = "https://api.hiapi.ai/v1/generate"
API_KEY = os.environ["HIAPI_API_KEY"]
# 在一个系列中保持稳定
AVATAR = "<avatar_identifier>"
def generate_clip(script: str, voice: str, aspect_ratio: str = "9:16",
duration: int = 30) -> dict:
payload = {
"model": "heygen-avatar-iv",
"input": {
"avatar": AVATAR,
"script": script,
"voice": voice,
"aspect_ratio": aspect_ratio,
"duration": duration,
},
}
resp = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = generate_clip(
script="这是数字人流水线的三十秒测试。",
voice="<voice_identifier>",
)
print(job)
日后受益的设计要点:
- 默认值反映你最常用的片段。 如果大多数输出是竖屏短片段,就默认这些,很少覆盖。
- 形象放在模块级。 数字人选择只存在一个地方,重新换品牌只需改一行。
- 返回完整响应。 不要立即提取 URL 并丢弃 job 对象;你会需要该标识符用于日志和重试。
- HTTP 错误时抛出异常。 批量循环中的静默失败比崩溃更糟。
- 显式处理异步步骤。 添加一个小的
poll(job_id)辅助函数,而不是在生成函数内部 sleep。
将响应处理逻辑固定到模型页上记录的契约——job 状态和结果获取的字段名是最可能与你的假设发生偏差的部分。
撰写口播脚本并控制节奏
数字人视频是音频优先的。在纸面上读起来没问题的脚本,朗读时往往过长,而生成后再裁剪意味着为将要剪掉的文字付渲染费。
先按长度写,再裁剪
在调用 API 之前估算时长。舒适的语速约为每分钟 130–160 词;对于观众需要跟上的技术内容,使用较低端。因此 30 秒片段大约需要 65–80 词,60 秒片段大约 130–160 词。按此预算起草,用计时器大声朗读,然后删减。如果必须删减,删整句而非单词——句子级删减能保持节奏完整。
为耳朵而写
- 短句。 每句一个观点。从句是理解力下降的地方。
- 不要仅依赖视觉的引用。 “如下所示”在没有幻灯片时行不通。
- 把重点前置。 短视频观众在最初几秒就做决定;把主张放在第一句。
- 拼出 TTS 会读错的内容。 缩写、版本字符串和大小写异常的产品名,应按其应被发音的方式书写。
按时间线控制节奏
将脚本按目标长度铺排为时间块:
0–5s 钩子:主张或问题
5–20s 主体:机制,两到三句
20–28s 细节:值得保留的一个数字或例子
28–30s 收尾:单一行动号召
这种块结构同时可作为评审产物——评审者可以否决某个块,而无需你重新渲染任何内容。将每个片段的脚本放在独立文件中,与渲染它的代码一起版本控制,下一节的批量循环就变得完全可复现。
设置宽高比、时长和输出
在首次渲染之前,根据目标平台决定方向和长度。以第二种方向重新渲染成品片段纯属浪费,而重新编辑过长的片段意味着音频也要重新生成。
宽高比
- 9:16 竖屏 —— 短视频信息流的默认:shorts、reels、stories 和移动优先的投放位。优先为此设计构图;尽可能从竖屏母版裁剪出其他比例。
- 16:9 横屏 —— 嵌入式播放器、落地页、文档视频和演示场景。
- 1:1 方形 —— 偏好方形的信息流投放位。适合作为次级衍生版本。
如果你的活动需要两种方向,将它们视为两个不同的任务,使用不同脚本,而非将同一脚本渲染两次——适合 30 秒竖屏的一句台词,在更短的方形剪辑中往往会留下冷场。
时长
根据上一节的脚本预算设置时长,而不是反过来。传入与实际朗读长度匹配的时长;被填充或句中截断的片段看起来就像坏了。将各平台目标放在配置中,便于调整:
TARGETS = {
"vertical": {"aspect_ratio": "9:16", "duration": 30},
"horizontal": {"aspect_ratio": "16:9", "duration": 45},
}
输出
自行下载并存储成品片段,而不是依赖临时结果 URL。一个简单的约定——{clip_id}-{orientation}-{version}.mp4——可保持衍生版本可追溯,并让过时文件一目了然。将 job 标识符与文件一起记录,使任何片段都能追溯回其确切的请求。
计费按你请求的生成进行——按时长和片段数量——因此在渲染前精简脚本是你可用的最便宜的优化。当前费率见定价面板。
批量生成多个片段
有了可用的函数,批处理就是对任务列表的循环。关键在于每个任务都是对一个片段的完整描述。
JOBS = [
{"id": "launch-vertical", "script_file": "scripts/launch.txt",
"voice": "<voice_a>", "aspect_ratio": "9:16", "duration": 30},
{"id": "launch-square", "script_file": "scripts/launch_sq.txt",
"voice": "<voice_a>", "aspect_ratio": "1:1", "duration": 20},
{"id": "changelog-vertical", "script_file": "scripts/changelog.txt",
"voice": "<voice_b>", "aspect_ratio": "9:16", "duration": 30},
]
results = []
for job in JOBS:
with open(job["script_file"]) as f:
script = f.read().strip()
print(f"submitting {job['id']} ({len(script.split())} words)")
resp = generate_clip(
script=script,
voice=job["voice"],
aspect_ratio=job["aspect_ratio"],
duration=job["duration"],
)
results.append({"id": job["id"], "job": resp})
值得采纳的模式:
- 脚本作为文件,而非字符串字面量。 它们可被评审、对比差异,并在不同方向间复用。
- 词数日志。 打印每个任务的词数,可在花费渲染之前发现将要超出时长的脚本。
- 稳定的 job id。 在输出文件名和日志中使用它们,使二十次运行中的失败片段可被识别。
- 软失败,再报告。 将每次提交包裹在 try/except 中,收集失败并继续——一个坏脚本不应中止整批。
- 遵守速率限制和并发。 从串行开始;只有在串行运行稳定后才添加有界工作线程池。
- 持久化结果列表。 将 job id 写入 JSON 文件,使部分完成的批次可以续跑而非重启。
常见故障点与检查
这些是最先暴露的问题。每个都有廉价的隔离检查。
输入格式错误
模式错误是最常见的首次失败。检查: 用相同标识符运行原始 curl 命令。如果 curl 成功而 Python 失败,bug 在你的序列化——通常是类型不匹配,例如整型 duration 处传了字符串,或脚本文件末尾多出换行符。
音频与脚本不匹配
如果语音说的与屏幕上意图不符,或片段无声,则音频组有误。检查: 确认请求是文本驱动还是音轨驱动,并确认你传入了匹配的字段。同时提供音轨和脚本字段是典型的无声冲突——决定哪个优先并移除另一个。
方向错误或出现黑边
片段回来带有黑边或意外画框。检查: 验证 aspect_ratio 确实到达了负载——函数中的默认值可能静默覆盖你以为传入的值。发送前记录组装好的负载。
时长不匹配
片段在句中截断或拖尾。检查: 将脚本词数与时长预算对比。修脚本而非时长,除非目标本身有误。
系列中的形象漂移
同一活动中的片段看起来像不同主播。检查: 确认数字人标识符来自单一常量,而非逐任务配置。
输出截断或缺失
job 成功但文件不完整。检查: 在下载前确认 job 达到终态成功,并确认你遵循了模型页上的获取契约,而非猜测 URL。
通用规则:一条测试片段、一次 curl 请求、一次一个变量。先通过 heygen-avatar-iv 模型做一次简短的竖屏渲染,端到端验证,然后再让循环扩展。