how-tos

HeyGen Avatar 6 API 指南:用 cURL 和 Python 生成第一个说话视频

Poyo.ai Team
5 min read
Share:

HeyGen Avatar 6 API 指南:用 cURL 和 Python 生成第一个说话视频

这份 HeyGen Avatar 6 API 指南带你从拿到 API 密钥一直走到在 PoYo 上生成一个完整的说话视频。你只需用模型 ID heygen-avatar-6(或 heygen-avatar-6-turbo)提交一个 JSON 请求,保存返回的任务 ID,然后轮询直到 MP4 生成完毕。下面所有请求体都遵循 PoYo 文档的格式;如果想先看看有哪些输入,HeyGen Avatar 6 模型页上有 Playground。

开始之前

  • 在 poyo.ai/dashboard/api-key 创建密钥,并导出为 POYO_API_KEY。密钥只放在服务器端。
  • 把所有输入文件托管在公开、可直接下载的 HTTP 或 HTTPS URL 上。PoYo 会自己去拉取媒体,不接受在请求中直接上传。
  • 选择档位。两个 ID 接受相同的字段。Turbo 在 1080p 下每秒 10 积分($0.05);Avatar 6 每秒 20 积分($0.10)。参见 Avatar 6 vs Turbo。

用 cURL 发出第一个 HeyGen Avatar 6 API 请求

最快的第一个请求完全不需要媒体文件:由 HeyGen 公共数字人朗读你的文本。

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

成功的响应包含 "code": 200 和 data.task_id,status 为 not_started。这表示任务已排队,而不是视频已生成。接着轮询:

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

状态有 not_started、running、finished 和 failed。状态为 finished 时,MP4 位于 data.files[] 中 file_type 为 video 的条目,data.credits_amount 显示扣费金额。状态为 failed 时,读取 data.error_message。

有上限的 Python 轮询循环

在 2026 年 11 月 19 日的上线当天测试中,短文本片段从提交到出结果大约需要 2 到 2.4 分钟。下面的循环每 5 秒轮询一次(状态文档建议 2–5 秒),15 分钟后停止,并且超时后绝不重新提交,因为第二次提交就是第二个计费任务。

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
    return body["data"]


def generate(payload, timeout_s=900):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    print("task", task_id, flush=True)
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
            return videos[0], task.get("credits_amount")
    raise TimeoutError("still running; poll this task again later: " + task_id)


url, credits = generate({
    "model": "heygen-avatar-6",
    "input": {
        "image_urls": ["https://example.com/presenter.png"],
        "audio_url": "https://example.com/speech.mp3",
        "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
        "resolution": "1080p",
    },
})
print(url, credits)

生产环境中,请在顶层添加 callback_url 来代替轮询。任务变为 finished 或 failed 时,PoYo 会 POST 同样的任务对象(不带 code / data 外层包装),并在 X-Webhook-Signature 中附带 HMAC-SHA256 签名;签名规则见 Webhook 文档。

HeyGen Avatar 6 API 的三种输入模式

没有模式开关。有 avatar 就是公共数字人模式;否则有 video_url 就是参考视频模式;否则按照片模式运行。每个请求只使用一种模式的输入。

公共数字人 + 文本模式

见上文示例。avatar 是 1,248 个公共形象之一,text 最多 1,000 个字符,voice 是 102 个音色之一(默认 Warm Pro Narrator)。如何从目录中挑选形象和音色,见文本生成数字人教程。

公共数字人 + 自有音频模式

把 text 和 voice 换成 audio_url。aspect_ratio 仍然有效:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}

照片模式

一张真人照片加语音。视频保持照片的宽高比,所以发送前先把照片裁成你想要的画幅。callback_url 与 model 同级,不放在 input 里面:

{
  "model": "heygen-avatar-6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "image_urls": ["https://example.com/presenter.png"],
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
    "resolution": "1080p"
  }
}

参考视频模式

适用于动画或插画角色。video_url 是该角色的一段视频;image_urls 可选地再加一张同一角色的静态图。输出保持视频片段的宽高比:

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "video_url": "https://example.com/cartoon-character.mp4",
    "image_urls": ["https://example.com/cartoon-character.png"],
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "2K"
  }
}

HeyGen Avatar 6 API 字段校验规则

提交前请在自己的代码中检查这些规则;它们都是文档中写明的限制。

字段模式规则
model全部heygen-avatar-6 或 heygen-avatar-6-turbo
image_urls照片(必填)、参考视频(可选)恰好包含一个 URL 的数组
video_url参考视频至少 2 秒,最大 50 MB
avatar公共数字人列出的 1,248 个名称之一
audio_url照片、参考视频;或在公共数字人中替代 text2–60 秒,最大 15 MB
text公共数字人1–1,000 个字符
voice使用 text 的公共数字人102 个名称之一
prompt全部最多 1,200 个字符
aspect_ratio公共数字人16:9、9:16、1:1、4:5、5:4
resolution全部1080p(默认)或 2K

数字人和音色名称匹配时不区分大小写、忽略多余空格,但文档注明了一个例外:Hope 和 Hope (末尾带空格)是两个不同的音色。输入 schema 不允许额外字段,所以不要发送 HeyGen 自家 API 中的原生选项,例如 motion_expressiveness 或 motion_prompt;在 PoYo 上,动作指令写在 prompt 里。

需要处理的错误

务必读取响应体中的 code。部分校验错误会以 HTTP 200 加 "code": 400 的形式返回,只检查 HTTP 状态码是不够的。

响应体 codeerror.type处理方式
400validation_error 等修正输入:音频不在 2–60 秒内、数字人名称不存在、混入了其他模式的字段。不要原样重试
401authentication_error检查 Authorization: Bearer 请求头
402insufficient_credits_error充值,或等待运行中的文本任务结算(见下文)
429rate_limit_error退避后重试
500 / 502 / 503internal_error、upstream_error、service_error指数退避重试

音频时长、参考视频时长和数字人名称在提交时就会检查,所以这类错误会立即返回 400,而不是几分钟后任务失败。

402 有一个 HeyGen 特有的坑。在上线当天的测试中,提交了两个文本任务之后,第三个请求(Turbo,2K,22 个单词)返回 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." 文本任务在运行期间会占用积分,所以即使最终费用在余额之内,连续提交文本任务也可能触发 402。请把文本任务排队处理,或者直接把错误信息展示给用户,因为它已经写明了两个数字。

第一笔 HeyGen Avatar 6 API 账单如何计算

PoYo 按输出秒数计费,向上取整到整秒(1 积分 = $0.005):

模型1080p2K
heygen-avatar-6-turbo10 积分($0.05)/ 秒18 积分($0.09)/ 秒
heygen-avatar-620 积分($0.10)/ 秒29 积分($0.145)/ 秒
  • 使用 audio_url(所有模式):按音频时长向上取整计费,在提交时扣除。Avatar 6 1080p 下一段 12.3 秒的音频为 13 × 20 = 260 积分($1.30)。
  • 使用 text:提交时预留积分,任务结束时按成片时长结算。在我们的测试中,Turbo 上 27 个单词的脚本生成了 10.16 秒视频,按 11 秒计费,按当前价格为 110 积分(11 秒 × 10,$0.55);Avatar 6 上 21 个单词的脚本生成了 6.88 秒视频,按 7 秒计费,按当前价格为 140 积分(7 秒 × 20,$0.70)。

对账时以已完成任务的 data.credits_amount 为准。更多示例见 HeyGen Avatar 6 API 价格。

常见问题

如何用 Python 调用 HeyGen Avatar 6 API?

用 requests 向 https://api.poyo.ai/api/generate/submit POST JSON,然后像上面的循环那样,带截止时间轮询 /api/generate/status/{task_id}。任何 HTTP 客户端都可以,不强制使用 SDK。

HeyGen Avatar 6 API 有回调吗?

有。在请求顶层添加 callback_url。任务完成或失败时,PoYo 会 POST 任务数据。

为什么我的 HeyGen Avatar 6 API 请求返回了 HTTP 200 却没有任务?

请读取响应体。只要 code 不是 200,即使 HTTP 状态是 200,请求也已失败;原因见 error.message。

可以直接向 HeyGen Avatar 6 API 上传文件吗?

不可以。image_urls、video_url 和 audio_url 接受的是公开的 HTTP 或 HTTPS URL,由 PoYo 下载。

HeyGen Avatar 6 API 的结果保留多久?

生成的视频在创建后 3 天内可访问。请把 MP4 下载到你自己的存储中。

Share: