为什么需要
媒体生成在成功时计费。如果连接在 VibeToken 接受请求之后、响应把生成id 送达之前断开,你手里就没有可轮询的任务句柄 —— 而盲目重试会创建(并在
成功时计费)第二个生成任务。
提供幂等 id 可以同时堵住这两个口子:
- 重试是安全的。 使用已经用过的 id 再次请求,会直接重放已有的生成任务
—— 相同的
id、当前的status、完成后附带data—— 而不是新建一个。 不会重复扣费。 - 丢失的任务可以找回。
GET /v1/videos/generations?client_request_id=...返回在该 id 下创建的生成任务,即使你从未收到原始响应。
POST /v1/images/generations、POST /v1/videos/generations、
POST /v1/audio/speech、POST /v1/audio/generations。不带 id 的请求行为与
之前完全一致。
提供 id
发送Idempotency-Key 请求头(两者都提供时以请求头为准),或在 JSON 请求体
中加入 client_request_id 字段。每个逻辑请求使用一个全新的唯一值 —— UUID
最合适。id 为 1–128 个可见 ASCII 字符,作用域为你的账户。
连接中断后找回任务
如果 POST 超时或连接被重置,不要立刻认定任务丢失 —— 先查一下:200—— 请求确实已经生效。响应就是标准的生成对象(id、status、 完成后有data[].url);照常继续轮询GET /v1/videos/generations/{id}。404—— 请求从未到达 VibeToken。用同一个 id 重试 POST;如果这个 404 恰好与一个仍在受理中的请求赛跑,重试也只会重放它。
/v1/images/generations 和 /v1/audio/generations 上也可用。
重试语义
- 重放的请求按任务当前所处状态返回(
pending、success或failed)—— 不会重新执行任务,重试请求的请求体会被忽略。 failed的生成不会在同一个 id 下重试(失败不扣费)。想再试一次,请换 一个新 id。- 两个使用相同 id 的并发请求是安全的:只会创建一个生成任务,另一个请求会重放 它。