如何使用 Webhook 回调

Webhook 用于在视频生成任务状态变化时，由 PixVerse API 主动将结果推送到你的服务端，减少频繁轮询任务状态。

支持功能

功能	接口	支持情况
文生视频	`/openapi/v2/video/text/generate`	支持
图生视频	`/openapi/v2/video/img/generate`	支持
首尾帧	`/openapi/v2/video/transition/generate`	支持
对口型	`/openapi/v2/video/lip_sync/generate`	支持
视频延长	`/openapi/v2/video/extend/generate`	支持
音效生成	`/openapi/v2/video/sound_effect/generate`	支持
参考生视频	`/openapi/v2/video/fusion/generate`	支持
多帧生成	`/openapi/v2/video/multi_transition/generate`	支持
主体替换	`/openapi/v2/video/swap/generate`	支持
视频重绘	`/openapi/v2/video/restyle/generate`	支持
动作模仿	`/openapi/v2/video/mimic/generate`	支持
视频编辑	`/openapi/v2/video/modify/generate`	支持
视频超清	`/openapi/v2/video/upscale/generate`	支持

接入步骤

前往 Webhook 管理页面创建 Webhook，保存 webhook_id 与 Secret Key。

调用支持 Webhook 的生成接口时，在请求体中传入 webhook_id。

服务端接收回调后验证签名，完成幂等处理，并返回 HTTP 200 和纯文本 ok。

请求示例：

{
  "aspect_ratio": "16:9",
  "duration": 5,
  "model": "v5.5",
  "prompt": "傍晚的市郊公交站，霓虹灯初亮",
  "quality": "720p",
  "webhook_id": "1234"
}

回调请求

Headers

Header	类型	说明
`Webhook-Timestamp`	string	Unix 时间戳（秒）
`Webhook-Nonce`	string	32 位随机字符串
`Webhook-Signature`	string	Base64 编码的 HMAC-SHA256 签名
`Ai-trace-id`	string	请求追踪 ID
`Content-Type`	string	固定为 `application/json`

Body 示例

{
  "id": "123456789",
  "status": 1,
  "url": "https://example.com/video.mp4",
  "size": 10.5,
  "has_audio": true,
  "credits": 100
}

签名验证

将时间戳、随机字符串和按字段名排序后 URL 编码的请求体以换行符连接：

{timestamp}\n{nonce}\n{url_encoded_payload}

使用 Webhook Secret Key 计算 HMAC-SHA256，再进行 Base64 编码：

signature = Base64(HMAC-SHA256(secret_key, sign_string))

Python 示例：

响应要求

接收成功后必须返回：

HTTP/1.1 200 OK
Content-Type: text/plain

ok

返回非 200 状态码或响应体不是小写 ok 时，平台会重试。

重试机制

失败后依次在约 2 秒、10 秒、30 秒、1 分钟、5 分钟、15 分钟、1 小时和 4 小时后重试；间隔可能包含少量随机抖动。

安全建议

在处理业务数据前始终验证签名。

建议只接受 5 分钟内的时间戳，防止重放攻击。

Webhook 接收地址必须使用 HTTPS。

Secret Key 不得放在客户端代码或版本控制系统中。

使用时间安全的签名比较函数。

使用任务 id 去重，确保重复推送时处理逻辑幂等。

Webhook 回调

如何使用 Webhook 回调#

支持功能#

接入步骤#

回调请求#

Headers#

Body 示例#

签名验证#

响应要求#

重试机制#

安全建议#