用 heygen-avatar-v 和 hiapi 的 API 将脚本转化为口播短视频

短视频口播内容——创始人近况更新、产品演示、UGC 风格的广告口播——通常意味着要预约真人、准备麦克风，还要再做一遍剪辑。hiapi 上的 heygen-avatar-v 把这一切压缩成一次 API 调用：发送脚本或音频文件，即可拿回一段唇形同步的虚拟形象视频，带有自然的闲置动作和一条字幕轨，可直接投入短视频信息流。本文会走一遍实际的 /v1/tasks 工作流、一段真实生成的视频片段、在围绕它搭建流水线之前值得了解的约束，以及从 hiapi 的 /api/pricing 实时拉取的定价。如果你想要的是虚拟形象本身的提示词级风格技巧，heygen-avatar-v prompt recipes 已有所覆盖——本文讲的是如何把该模型接入一条可复用的短视频流水线。

heygen-avatar-v 实际输出什么

heygen-avatar-v 是一个数字人视频模型，而不是 Sora/Kling 意义上的文生视频生成器——它用文本脚本或上传的音频文件驱动一个预设的 HeyGen 虚拟形象，返回一段视频：虚拟形象的嘴部与语音唇形同步，并带有细微的持续动作（眨眼、轻微头部移动、肩部晃动），因此看起来不会像一张静态肖像。这种“即使闲置时也在动”的行为，正是可用的短视频片段与一眼假的会说话照片之间的分界线。

模型由两种输入驱动，二者互斥——你发送其中一个或另一个：

• prompt——文本脚本；由 hiapi 的 TTS 朗读并驱动唇形同步
• audio_url——指向预先录制的语音轨（你自己的配音、克隆音色，随便什么）的公开 URL，由它来驱动唇形同步

没有 duration 字段。片段长度完全取决于脚本或音频播放多久——40 个词的一行会比 200 个词的一行产出更短的片段。这对成本规划很重要，下文会讲。

可选字段用于完善风格：avatar（从 HeyGen 预设库中选择）、voice（仅与 prompt 一起使用，与 audio_url 一起时被忽略）、aspect_ratio（9:16 用于 Reels/TikTok/Shorts，16:9、1:1）、resolution、background（纯色或场景——但请见下面的坑）、caption（生成一条字幕轨）以及 output_format（mp4 或 webm，后者带透明背景，便于合成到自己的场景上）。

真实片段：输入脚本，输出带字幕的虚拟形象视频

下面是一段实际的 heygen-avatar-v 输出——虚拟形象念出一行脚本，短语之间有可见的闲置动作，并带有同步的字幕轨：

注意没有发生什么：虚拟形象在句子之间不会僵住，字幕会跟随语音，而不是事后贴上去的。这种组合——动作连续加上定时字幕——正是选择这个模型、而不是在编辑器里给静态虚拟形象图片配一段旁白的全部理由。

坑：两条会咬到初版流水线的问题

caption 给的是字幕附属文件，不是硬字幕。 设置 caption: true 会在视频输出之外返回一个同步的 .srt 文件——它不会把文字烧进视频帧。如果你想要屏幕上出现字幕文本（大多数短视频平台的那种观感），需要单独用这个 .srt 文件做一次烧录（ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4，或用你平台原生的字幕导入功能）。把 API 的“字幕”当作数据，而不是渲染好的画面。

background 只对插画风虚拟形象生效，对实拍风无效。 HeyGen 的虚拟形象库混合了照片级实拍虚拟形象与插画/动画风虚拟形象。background 参数能成功替换插画风虚拟形象背后的场景，但实拍风虚拟形象无论你传什么，都会保留其原始录制的背景——模型不会把它抠掉。如果你的流水线假设每个虚拟形象都接受背景覆盖，请先测试你要用的那个具体 avatar ID，再假设它会按你预期的方式合成。对于你想放到自己背景上的实拍风虚拟形象，可靠的做法是 output_format: webm（透明）。

成本：按输出秒数计费，而不是按调用次数

根据 hiapi 实时的 /api/pricing，heygen-avatar-v 按每输出秒 $0.15 计费——无论分辨率或宽高比都是统一费率。由于没有时长输入，你的实际成本取决于脚本或音频播放多久：

脚本长度（约）	输出时长	成本
简短钩子句	约 5 秒	$0.75
一段短视频节拍	约 10 秒	$1.50
多句推销	约 20 秒	$3.00
完整的 30 秒广告口播	约 30 秒	$4.50

由于成本随语音长度而非你事先设定的参数伸缩，实用的做法是在提交任务之前先给脚本计时（朗读一遍，或用 TTS 长度估算器跑一下），而不是等片段渲染完才发现账单。

流水线：提交、轮询、在过期前下载

heygen-avatar-v 运行在 hiapi 的异步 /v1/tasks 端点上——与平台上其他所有基于任务的模型一样，是“先创建后轮询”的形态。这个工作流特有的一个细节：任务在 handling 与 success 之间会经过一个 archiving 阶段，此时平台正在完成视频与字幕附属文件的收尾，所以不要在你的轮询循环里把 archiving 当作终止状态。

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

两条在大规模使用时不可跳过的运维说明：

• 立即下载。 与 hiapi 的每个任务输出一样，返回的 URL 带有 expireAt，不适合长期链接——任务一成功，就把字节（视频和 .srt）拉到自己的存储中。
• 不要为了“检查 schema”而发一个只有最小字段的载荷。 因为严格来说只有 prompt 或 audio_url 是必填，其他字段都会静默使用默认值，一个只有 {"prompt": "test"} 的载荷不会返回 400——它会派发一次真实的、可计费的渲染。请对照文档或用一个故意无效的值得到 4xx 响应来校验字段名，而不是对着真实端点省略字段。

FAQ

我可以用自己的声音代替 hiapi 的 TTS 吗？ 可以——传入 audio_url 而不是 prompt，给出你录音的公开 URL，虚拟形象就会跟随那条音轨做唇形同步，而不是从文本合成语音。

caption 选项会把字幕烧进视频里吗？ 不会。caption: true 返回一个单独的 .srt 文件，与输出视频的音频同步。如果你想要屏幕上的字幕文本，请自行把它作为后处理步骤烧录进去。

我能控制片段时长吗？ 不能直接控制——没有 duration 参数。输出长度由脚本长度（使用 prompt 时）或音频文件长度（使用 audio_url 时）决定。

为什么我指定的背景没有出现？ background 只对 HeyGen 库中的插画/动画风虚拟形象有效。实拍、照片级虚拟形象会保留其原始录制的背景；此时请改用 output_format: webm 获得透明输出，由你自己来合成。

它支持哪些分辨率和宽高比？ 最高 4K，支持 9:16、16:9 和 1:1 宽高比选项——覆盖竖屏短视频信息流到宽屏和方形投放。

要点

在 hiapi 上搭建短视频虚拟形象流水线，归结为几个具体事实，而不是靠猜：成本是每输出秒 $0.15（所以要在提交前给脚本计时，而不是提交后），字幕输出是一个需要你自行烧录的 .srt 附属文件，背景替换只对插画风虚拟形象有效，你的轮询循环需要把 archiving 与 handling 一样视为非终止状态。在硬编码预算之前，请查看 hiapi 的定价页面上的当前数字，完整字段参考请见模型页面。如果你准备好动手了，从仪表盘获取一个 API key，从一个短脚本开始——5 秒的输出就足以确认你的虚拟形象、宽高比和字幕处理都正常，然后再扩大到整批。