「视频头像」区的 webhook：视频就绪时，通知发到你的服务器

「视频头像」板块里的 webhook，是一种不用手动刷新页面就知道视频已就绪的方式：渲染一结束，一条 POST 请求就会发到你服务器的地址，接下来由你的服务器决定怎么做——把链接存进数据库、把文件交给客户端，或者启动下一步。这个标签页适合批量做视频、或把头像生成集成进自己产品的人：与其不停地检查「好了没有」，不如在正确的时刻收到一条简短通知。

为什么真的需要它

视频渲染不是瞬间完成的，开着标签页干等没有意义。按平台 2026 年 9 月 7 日的实测，5 秒的 Kling 3.0 1080p 视频平均渲染约 115 秒，95% 的情况在 165 秒内完成。同一任务在 Sora 2 上平均约 145 秒。如果每隔几秒查一次状态，一条视频就会积累几十次空请求；而 webhook 只在结果真正出现时来一次。

规模也说明问题。按平台 30 天（2026 年 9 月 3 日至 10 月 2 日）的生成日志，共启动 3,292 个视频任务，其中 2,369 个成功完成。视频在后台计算、完成时间各不相同——手工根本盯不过来，而一个靠谱的通知处理器可以自己搞定。

Webhooks 标签页能给你什么

这里讲的都是通知投递，没有玄学。你注册地址、选择要订阅的事件，然后拿到签名密钥。已注册端点就列在这里：能看到地址、所选事件、状态，以及端点是否已设置密钥。密钥可以重新生成（旧的立刻失效），也可以把端点整个删掉。

事件只针对你自己的视频：别人的渲染不会外发，哪怕它同一时刻刚好完成。这里还有「已投递事件」日志——可以确认消息确实到了你的服务器。

如何开始：分步操作

1. 打开「视频头像」板块，用直链 /zh/avatars?tab=webhooks 进入 webhook 面板。
2. 登录账号：访客无法设置，点击时会弹出登录窗口。
3. 在「端点地址」里填写你服务器的公开 HTTPS 地址，例如 https://example.com/avatar-webhook。HTTP 不行——投递和签名都依赖加密通道。
4. 勾选需要的事件。如果一个都不选，就默认订阅全部事件。
5. 点「添加端点」。创建后立刻显示签名密钥——复制并保存好，之后不会再显示。
6. 如果还没有自己的服务器，点「使用我们的接收器」——通知会直接累积在标签页里的「已投递事件」日志中。

如何确认请求真的来自我们

每条请求都带一个 signature 请求头，它是用你的密钥对请求原始正文算出的 HMAC-SHA256。在你这边按同样方式算一遍并比对：不一致就丢弃请求。我们的接收器就是这么做的，签名错误会返回 401。密钥保存在服务器的环境变量里，不要放进客户端代码。

请求里有什么

正文是普通 JSON，包含事件类型和实体数据。比如视频就绪时，就是 avatar_video.success 事件，里面带着这条片段的标识。可用事件类型的完整列表会显示在标签页里：你可以逐个看，只保留服务真正需要的那几种。

要花多少钱

注册端点、重新生成密钥、删除端点和查看事件日志都不消耗 token——这是通知设置，不是生成。Token 只花在视频本身上：价格在运行前显示，任务失败时已扣的会退回。没有订阅：新用户会获得用于首次尝试的初始 token。

搭配使用

• 「批量任务」——一个任务跑几十条视频，webhook 免去手工盯完成状态。
• 「媒体库」——存放素材和成品文件。
• 「视频翻译」与「视频切片」——生成之后的下一步。

常见问题

什么样的地址可以用于 webhook？

只能是公开的 HTTPS 地址。本地地址和 HTTP 都不接受：通知要走安全通道，你的服务器也要能从外网访问。

没有自己的服务器也能收到通知吗？

可以。点「使用我们的接收器」，事件会累积在标签页的「已投递事件」日志里，无需自己的后端就能查看。

签名对不上怎么办？

检查你是否用请求的原始正文（而不是解析后的 JSON）来计算 HMAC-SHA256，以及是否用的是当前密钥：重新生成后旧密钥会立刻失效。

这是付费的吗？

设置 webhook 不消耗 token。Token 只用于视频生成——价格在运行前显示；没有订阅，新用户会获得初始 token。