HeyGen API 快速上手：从 API Key 到生成第一支 AI 视频

HeyGen 提供了一套面向开发者的视频生成 API。它把头像、声音、图片、剪辑、音乐和素材编排成一条确定性的渲染流水线，最终把可直接上线的视频交付到你自己的技术栈里。你不需要打开任何可视化编辑器，只要发一个 HTTP 请求，就能拿到一个 MP4 的地址。适合的对象是那些需要把视频生产接进自有系统的团队：产品培训、合作伙伴教程、引导式支持、批量本地化，以及任何今天还在靠人工重复录制的场景。站内也有对应的工具页可以参考：HeyGen。

这套 API 的定位不是「帮你做一支视频」，而是「让视频成为你系统里的一个可编程环节」。从一支视频到成千上万支批量渲染，走的是同一套接口。下面按实际动手的顺序，把从拿密钥到拿到成片的路径拆开讲。

准备工作

账号与 API Key

第一步是在 API 控制台创建一个密钥。后续每一个请求都要带上它。密钥的创建入口在 HeyGen 的开发者控制台里，创建完成后建议立刻导出到环境变量，不要写死在代码里：

export HEYGEN_API_KEY="your-api-key-here"

密钥支持轮换，轮换的具体做法在 API Key 相关文档里有说明。如果你的项目由多人协作，建议每个环境使用独立的密钥，方便单独吊销。

权限范围

密钥带有权限范围（Permission Scopes）的概念。也就是说，一个密钥能做什么、不能做什么，是在创建时就限定好的。给自动化任务用的密钥，应当只授予它真正需要的能力，而不是直接给一个全权限密钥。

基础地址与鉴权头

所有请求都发往同一个基础地址，鉴权通过请求头完成：

Base URL：https://api.heygen.com
鉴权头：X-Api-Key: <your-key>

注意鉴权头的名字是 X-Api-Key，不是常见的 Authorization: Bearer。这是新手最容易踩的一个坑，写错了会直接返回 401。

先验证密钥是否可用

在写任何业务代码之前，先用一个只读接口确认密钥是通的：

curl "https://api.heygen.com/v3/users/me" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

这个接口返回当前密钥对应的用户信息。如果这里就失败了，后面所有步骤都不用继续排查。

在 Playground 里先试一次

如果不想立刻写代码，可以先用浏览器里的 Playground 发一个真实请求。它的价值和 curl 一样，都是用来确认「密钥 + 请求体」这一组合是有效的，区别只是不用配本地环境。

选择接入方式

HeyGen 提供两种接入路径，按团队规模区分：

自助接入：从 API Key 到第一支视频只需要几分钟。包含全部 API（头像、声音、Video Agent、翻译、口型同步），批量接口单次最多 100 个请求，并支持 Webhook。同时提供 REST、CLI 和 MCP 三种调用面。
企业接入：面向需要规模化生成头像的团队，提供更高的并发与速率上限、在 HeyGen Cloud 上的预留算力，以及由前置工程师参与定制的流程。

面向 AI Agent 的接入

如果你打算让 Claude Code、Codex、Cursor 这类工具直接帮你调用，HeyGen 的每个端点都自带 MCP server、llms.txt 和带类型的 schema。这意味着 agent 不需要你写胶水代码就能生成视频。文档索引文件位于 /llms.txt，可以用它来发现全部可用页面。

操作步骤

第一步：确定你要做哪一类视频

HeyGen 的接口按产出物划分，先想清楚目标再选端点，比先写代码再找接口省事得多。常见的几类：

创建头像：用一段视频训练数字分身，或者用一张照片生成头像。
Video Agent：给一句提示词，直接产出成片；之后还可以单独编辑某个场景。
HeyGen Video：从文本、图片或参考素材生成 5 到 15 秒的片段，最高 2K。
头像视频：指定头像、声音和脚本，最高可用到 Avatar V。
模板：把任意一支视频变成模板，之后每个观看者一次调用。
Look Packs：给头像换上一整套预设造型。
HyperFrames：用 HTML、CSS 和 JS 生成动态图形视频。
即时声音克隆：一段录音，几秒内得到一个 HeyGen Voice。
专业声音克隆：用 20 分钟以上的音频训练录音棚级声音。
文本转语音：从你的 HeyGen Voice 生成已完成或流式的语音。
视频翻译：支持 175 种以上语言，带声音克隆和口型同步。

本教程用 Video Agent 走通全流程，因为它只需要一句提示词，最适合验证链路是否打通。

第二步：发起一次 Video Agent 请求

Video Agent 会自己写脚本、挑头像、选声音，然后渲染。你只需要给一句描述：

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A presenter explaining our product launch in 30 seconds"}'

同样的请求用 Python 写是这样：

import requests

resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={"prompt": "A presenter explaining our product launch in 30 seconds"},
)
session_id = resp.json()["data"]["session_id"]

用 Node.js 写是这样：

const resp = await fetch("https://api.heygen.com/v3/video-agents", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.HEYGEN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "A presenter explaining our product launch in 30 seconds",
  }),
});
const { session_id } = (await resp.json()).data;

返回体里包含三个字段：

{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": null
  }
}

注意此时 video_id 还是 null，status 是 generating。这说明任务已经受理，但视频还没被分配出来。你可以打开 https://app.heygen.com/video-agent/{session_id} 实时看它构建的过程。

第三步：轮询拿到 video_id

Video Agent 是两段式的：先有 session，再有 video。所以要分两步轮询。第一步是等 session 上挂出 video_id：

import time

video_id = None
while not video_id:
    sess = requests.get(
        f"https://api.heygen.com/v3/video-agents/{session_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    video_id = sess.get("video_id")
    if not video_id:
        time.sleep(5)

对应的 curl 写法：

curl "https://api.heygen.com/v3/video-agents/sess_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

第四步：轮询视频直到完成

拿到 video_id 之后，再轮询视频本身，直到状态变成 completed 或 failed：

while True:
    video = requests.get(
        f"https://api.heygen.com/v3/videos/{video_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    if video["status"] in ("completed", "failed"):
        break
    time.sleep(10)

print(video["video_url"])

对应的 curl 写法：

curl "https://api.heygen.com/v3/videos/vid_xyz789" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

完成后的返回体长这样：

{
  "data": {
    "id": "vid_xyz789",
    "status": "completed",
    "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
    "duration": 32.5
  }
}

其中 video_url 就是可以直接下载或分发的 MP4 地址，duration 是时长（秒）。

第五步：用 Webhook 替代轮询

轮询能用，但在生产环境里不划算：任务多的时候会浪费大量请求，而且延迟取决于你的轮询间隔。更好的做法是在发起请求时带上 callback_url，让 HeyGen 在任务完成时主动回调你的服务。这样你就不需要写任何 while 循环。

第六步：用 CLI 或 MCP 简化调用

如果你不想手写 HTTP，HeyGen 提供了两个封装层，它们包的是同一套 API：

MCP Server：把 HeyGen 接进 Claude、Cursor 或任何支持 MCP 的 agent，由它替你发起调用。
CLI：提供 heygen video create、heygen video download 这类命令，可以在任意 shell 或 CI 任务里脚本化执行。

一个完整示例

下面把前面的步骤串成一个可以直接跑的 Python 脚本。它做四件事：创建 Video Agent 会话、等出 video_id、等视频完成、打印最终地址。

import os
import time
import requests

API_KEY = os.environ["HEYGEN_API_KEY"]
BASE = "https://api.heygen.com"
HEADERS = {"X-Api-Key": API_KEY}

# 1. 发起 Video Agent 会话
resp = requests.post(
    f"{BASE}/v3/video-agents",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"prompt": "A presenter explaining our product launch in 30 seconds"},
)
session_id = resp.json()["data"]["session_id"]
print("session:", session_id)

# 2. 等 session 上挂出 video_id
video_id = None
while not video_id:
    sess = requests.get(
        f"{BASE}/v3/video-agents/{session_id}",
        headers=HEADERS,
    ).json()["data"]
    video_id = sess.get("video_id")
    if not video_id:
        time.sleep(5)
print("video:", video_id)

# 3. 等视频渲染完成
while True:
    video = requests.get(
        f"{BASE}/v3/videos/{video_id}",
        headers=HEADERS,
    ).json()["data"]
    if video["status"] in ("completed", "failed"):
        break
    time.sleep(10)

# 4. 输出结果
if video["status"] == "completed":
    print("url:", video["video_url"])
    print("duration:", video["duration"])
else:
    print("failed:", video.get("failure_code"), video.get("failure_message"))

把 HEYGEN_API_KEY 导出到环境变量后直接运行即可。脚本里两个轮询间隔（5 秒和 10 秒）只是示例值，实际使用中应当结合你的任务量和速率限制来调整。

如果换成 CLI，同样的流程可以压缩成两条命令：heygen video create 负责创建，heygen video download 负责取回文件。适合放进 CI 任务里定时产出视频。

注意事项

视频状态为 failed

当视频最终状态是 failed 时，不要只看状态本身。调用 GET /v3/videos/{video_id}，检查返回体里的 failure_code 和 failure_message 两个字段，它们会说明失败原因。完整的错误码目录在 Error Codes 文档里。

401 Unauthorized

出现 401 时，先确认两件事：X-Api-Key 请求头是否真的带上了，以及这个密钥在 API 控制台里是否仍然处于可用状态。密钥被吊销或复制时漏了字符，都会导致这个结果。

429 Too Many Requests

429 表示撞上了速率或并发限制。正确的处理方式是读取响应里的 Retry-After 头，按它给出的时间退避重试，而不是立刻重发。企业方案提供更高的上限，具体额度参见 Usage Limits 文档。

400 download_failed

这个错误说明你传进去的某个 URL 抓取失败。要求是：该 URL 必须可以被公网访问，并且直接指向文件本身，而不是一个需要跳转或登录的页面。

批量接口的规模

批量 API 单次调用最多支持 100 个请求，并且包含 Webhook 支持。做大批量渲染时，应当按这个上限切分任务，而不是试图在一个请求里塞进更多。

版本迁移

如果你此前使用的是 v1 或 v2 版本，需要注意它们只支持到 2026 年 10 月 31 日。迁移前建议先看版本对比，确认字段和端点的差异。

价格与配额以官网为准

本文涉及的接口能力、并发上限、批量规模等，都可能随产品迭代调整。实际的价格、配额和可用性，请以 HeyGen 官网当前公布的信息为准。