博客

使用指南

通过 HiAPI API 使用 heygen-avatar-iv 生成短视频:开发者指南

数字人和音频输入、脚本节奏、宽高比和时长,以及批量生成——附可运行的 HiAPI 请求

2026年11月18日
封面图:深咖啡色底上宽大的燕麦与黄铜色编织带交错成扁平篮纹图案。
本页内容

为什么短视频选择 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       → 每个片段变化
        └── 脚本文本或音频来源

这种拆分引出两条实用规则:

  1. 参数化音频组,冻结形象组。 在代码中,将形象保持为模块级常量,将脚本和音色作为函数参数传入。这样从结构上确保一个系列的视觉一致性。
  2. 调试时一次只改一组。 如果片段看起来不对,只替换形象;如果听起来不对,只替换音频组。在付费渲染调用上做双变量调试代价高昂。

还要尽早确定你的音频组是文本驱动还是音轨驱动,因为这一选择会决定下一节的节奏——提供的音轨决定时序,而生成的语音则遵循你的脚本。

确切的字段名、可接受的值和默认值列在模型页上;读一遍并把它们固定在一个配置对象里,而不是把字面量散落到代码各处。

两个输入组——视觉形象和音频/声音——交织成一次生成调用。

用 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 模型做一次简短的竖屏渲染,端到端验证,然后再让循环扩展。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档