curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}HeyGen
HeyGen Avatar 6
HeyGen Avatar 6 API 可根据一张照片、一段动画角色参考视频或一个 HeyGen 公共形象,生成 1080p 或 2K 的口型同步说话视频,由 2–60 秒的音频驱动;使用公共形象时也可以由文字驱动。
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}- 提交后会返回
task_id。如果提供了callback_url,当任务状态变为finished或failed时,系统会向callback_url发送 POST 请求。 - 无论是否提供
callback_url,都可以通过统一的查询任务状态接口获取结果。
模型
- heygen-avatar-6 — 生成
1080p或2K的说话数字人视频,支持照片、参考视频和公共形象三种模式 - heygen-avatar-6-turbo — Avatar 6 的 Turbo 档,输入参数和模式与标准版相同
功能
- 三种输入模式:人物照片、动画或插画角色的参考视频,或 HeyGen 公共形象。
- 由音频决定时长:视频时长与语音音频一致,2 到 60 秒。
- 公共形象文字朗读:传入
text和可选的voice,形象会朗读这段文字。 - 动作引导:用
prompt引导手势、表情和姿态。 - 输出:
1080p或2K。公共形象视频可选16:9、9:16、1:1、4:5或5:4。
输入模式
| 模式 | 选择条件 | 输入 |
|---|---|---|
| 公共形象 | 传入 avatar | avatar,再加 audio_url 或 text |
| 参考视频 | 传入 video_url | video_url 和 audio_url,可在 image_urls 中加一张参考照片 |
| 照片 | 默认 | image_urls 和 audio_url |
prompt 和 resolution。aspect_ratio 和 voice 属于公共形象模式。每个请求使用同一种模式的输入。
必填参数
image_urls(字符串数组):照片模式。恰好一张要驱动的人物照片,使用image_urls[0]。video_url(字符串):参考视频模式。一段动画或插画角色的视频,时长至少 2 秒,大小不超过 50 MB。avatar(字符串):公共形象模式。形象与声音中列出的 1,248 个 HeyGen 公共形象之一,例如Abigail Sofa Front。名称匹配不区分大小写,也不受多余空格影响。audio_url(字符串):照片模式和参考视频模式的语音音频。公共形象模式下传audio_url或text二者之一。音频时长 2–60 秒,大小不超过 15 MB;视频时长与音频一致。text(字符串):公共形象模式,替代audio_url使用。形象要朗读的文字,最多 1,000 个字符。
可选参数
image_urls(字符串数组):参考视频模式。一张同一角色的参考照片。voice(字符串):公共形象模式下配合text使用。朗读文字的 HeyGen 声音,可选形象与声音中的 102 个声音之一。名称匹配不区分大小写,也不受多余空格影响。默认值:Warm Pro Narrator。prompt(字符串):引导形象的手势、表情和姿态,最多 1,200 个字符。aspect_ratio(字符串):公共形象模式。16:9、9:16、1:1、4:5或5:4。默认值:16:9。照片模式和参考视频模式下,视频沿用输入照片或视频的宽高比。resolution(字符串):1080p或2K。默认值:1080p。
输出
- 一个 MP4 视频文件。
- 视频时长跟随语音:等于
audio_url的时长,或形象朗读完text所用的时间。视频可能比音频短约十分之一秒。
示例
照片
{
"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"
}
}
参考视频
{
"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"
}
}
公共形象 + 音频
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
公共形象 + 文字
{
"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"
}
}
注意事项
- 所有媒体 URL 都必须可通过 HTTP 或 HTTPS 公开访问并可直接下载。
- 音频时长和参考视频时长在提交任务时检查。
avatar在提交任务时按形象列表检查。
授权
所有 API 接口都需要 Bearer Token 认证。
创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。
在请求头中添加:
Authorization: Bearer YOUR_API_KEY
请求体
application/json
响应
任务提交成功
业务状态码。200 表示成功,其他值都表示请求失败。请务必检查这个字段:部分参数校验错误会以 HTTP 200 返回,响应体里的 code 为 400。
200:成功400:请求参数无效401:API Key 缺失或无效402:积分不足403:没有权限404:资源不存在408:请求超时429:请求频率超限500:服务器内部错误502:上游服务错误503:服务暂不可用
详见错误码。
可用选项:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 示例:
200