幂等与重试

网络会超时，响应会丢失。幂等键让你在「不知道上一次成没成功」时可以放心重发。

哪些请求要带

创建视频任务、取消视频任务和登记素材这三个操作必须带请求头 Idempotency-Key。

怎么生成

• 每个新操作生成一个新值，例如 UUID，在发送前保存下来。
• 长度 8–128 个字符，以字母或数字开头，只用字母、数字和 .、_、:、-。
• 唯一性按团队、操作和键确定，不按 API 密钥区分：同一团队的两把 API 密钥用同一个键也会被当成同一个操作。

结果不明时

请求超时、连接断开或收到 500、503 时，用原请求体和同一个已保存的键重发。已经成功的操作会返回原响应，不会再创建一次，也不会再扣一次费。重试时绝不生成新值。

IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}

示例代码都这样处理：环境变量里已有 IDEMPOTENCY_KEY 就复用，没有才生成一次，并提示你保存。

冲突

取消的幂等

取消操作永久保留它的原响应。对同一个任务用新的键再次取消，会引用同一个取消操作，并返回当时冻结的任务状态。