Skip to main content

同步与异步

本页介绍视频和音频所使用的异步流程

提交 → 轮询模式

  1. POST /v1/videos/generations(或 /v1/audio/*)会立即返回 { id, status: "pending" }
  2. GET /v1/videos/generations/{id}(或 /v1/audio/generations/{id})返回同一对象,并带有更新后的 status。当 status == "success" 时,data[].url 会被填充。

方案 1 — 轮询

反复调用 GET 端点,直到状态进入终态。
推荐轮询频率: 每 3–5 秒一次。大多数视频生成会在 1–5 分钟内完成。

方案 2 — 回调 URL

在你的 POST 请求中包含 callback_url,即可跳过轮询。任务完成后,VibeToken 会将最终结果 POST 到该 URL。

回调请求体

成功:
失败:

回调安全

  • 在生产环境中,你的 callback_url 必须使用 HTTPS
  • 内部 / 私有网络 URL(localhost127.0.0.110.0.0.0/8192.168.0.0/16172.16.0.0/12、云元数据 IP)会被阻止,以防止 SSRF。
  • 回调采用 fire-and-forget 方式:目前没有自动重试,因此请确保你的 webhook 处理程序具有幂等性。
回调可以省去轮询的需要,并降低视频生成这类长耗时任务(通常 1–5 分钟)的延迟。

结果 URL

当配置了 R2 存储时,VibeToken 会将上游 provider 的 URL 重新托管在自己的 CDN 上——链接不会过期。当未配置 R2 时,你会直接收到上游 provider 的临时 URL(这类 URL 会过期,通常在 24 小时内失效)。

典型生成耗时

耗时因模型和 provider 负载而异。