跳转到主要内容
除了轮询状态接口,你还可以在提交任务时提供回调 URL,在生成完成时自动接收通知。

工作原理

  1. 提交时附带回调 URL:在提交任务时加入 callback_url
  2. 接收通知:任务完成(成功或失败)时,Vidgo API 会向你的 URL 发送 POST 请求
  3. 处理结果:你的服务器会收到完整的任务数据,包括生成的文件

回调请求

当任务状态变为 finished 或 failed 时,Vidgo API 会向你的回调 URL 发送一个扁平的任务对象。与状态接口响应不同,回调请求体没有 code 和 data 外层包装:

失败任务回调

要求

你的回调接口必须满足以下要求:
  • 公网接口:使用可公开访问的 HTTP(S) URL
  • 响应超时:在 30 秒内响应
  • 成功响应:应返回 HTTP 200-299 状态码

重试策略

如果投递超时、遇到网络错误或收到 5xx 响应:
  • 重试次数:最多自动重试 5 次
  • 重试间隔:每次重试之间分别间隔 60、120、240、480 和 600 秒
  • 最终失败:所有重试用尽后,不再继续发送回调
  • 客户端错误:4xx 响应会被记录,且不会重试
如果所有重试均失败,你仍可以通过轮询状态接口获取结果。

实现示例

Python (Flask)

Node.js (Express)

Go

安全最佳实践

验证请求:可以考虑增加签名验证机制,确保请求来自 Vidgo API
幂等性:将 Webhook 处理程序设计为幂等,以应对重复投递
异步处理:异步处理回调并尽快返回 200,避免超时
日志记录:记录所有 Webhook 请求,便于调试和监控

测试

使用 ngrok 进行本地测试

开发期间,你可以使用 ngrok 暴露本地服务器:

Webhook 与轮询对比

对于处理大量请求的生产系统,建议使用 Webhook,以减少 API 调用并即时获得通知。

后续步骤

任务状态

了解如何轮询任务状态

图像生成

使用 GPT-4o 生成图像

视频生成

使用 Sora 2 创建视频

快速开始

返回快速开始指南

其他生成文件

音频和 3D 工作流使用同一个 files 数组。file_type 可能是 audio、3d、image 或 other。该数组会保留模型资产、预览图、纹理、动画文件和时间戳文件。每一项还可能包含 label、format、content_type、file_name、file_size 和 metadata。请处理返回的每一个文件;metadata 字段是可选的。