Skip to main content

为什么需要

媒体生成在成功时计费。如果连接在 VibeToken 接受请求之后响应把生成 id 送达之前断开,你手里就没有可轮询的任务句柄 —— 而盲目重试会创建(并在 成功时计费)第二个生成任务。 提供幂等 id 可以同时堵住这两个口子:
  • 重试是安全的。 使用已经用过的 id 再次请求,会直接重放已有的生成任务 —— 相同的 id、当前的 status、完成后附带 data —— 而不是新建一个。 不会重复扣费。
  • 丢失的任务可以找回。 GET /v1/videos/generations?client_request_id=... 返回在该 id 下创建的生成任务,即使你从未收到原始响应。
支持的端点:POST /v1/images/generationsPOST /v1/videos/generationsPOST /v1/audio/speechPOST /v1/audio/generations。不带 id 的请求行为与 之前完全一致。

提供 id

发送 Idempotency-Key 请求头(两者都提供时以请求头为准),或在 JSON 请求体 中加入 client_request_id 字段。每个逻辑请求使用一个全新的唯一值 —— UUID 最合适。id 为 1–128 个可见 ASCII 字符,作用域为你的账户。
请在发送请求之前持久化保存这个 id —— 一旦响应没有到达,它就是你找回任务 的唯一凭据。

连接中断后找回任务

如果 POST 超时或连接被重置,不要立刻认定任务丢失 —— 先查一下:
  • 200 —— 请求确实已经生效。响应就是标准的生成对象(idstatus、 完成后有 data[].url);照常继续轮询 GET /v1/videos/generations/{id}
  • 404 —— 请求从未到达 VibeToken。用同一个 id 重试 POST;如果这个 404 恰好与一个仍在受理中的请求赛跑,重试也只会重放它。
同样的查询在 /v1/images/generations/v1/audio/generations 上也可用。

重试语义

  • 重放的请求按任务当前所处状态返回(pendingsuccessfailed)—— 不会重新执行任务,重试请求的请求体会被忽略。
  • failed 的生成不会在同一个 id 下重试(失败不扣费)。想再试一次,请换 一个新 id。
  • 两个使用相同 id 的并发请求是安全的:只会创建一个生成任务,另一个请求会重放 它。