> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetoken.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 幂等性

> 安全地重试媒体生成请求，并在连接中断后找回任务。

## 为什么需要

媒体生成在成功时计费。如果连接在 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 字符，作用域为你的账户。

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://vibetoken.cn/v1/videos/generations \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Idempotency-Key: 0b8f6a2e-4d1c-4f3a-9e57-1c2d3e4f5a6b" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek/deepseek-v4-pro",
      "prompt": "A slow pan across a foggy harbor at dawn"
    }'
  ```

  ```python Python theme={null}
  import uuid, requests

  key = str(uuid.uuid4())          # 发送前先持久化保存
  resp = requests.post(
      "https://vibetoken.cn/v1/videos/generations",
      headers={
          "Authorization": "Bearer sk-rb-xxxxxxxxxxxx",
          "Idempotency-Key": key,
      },
      json={
          "model": "deepseek/deepseek-v4-pro",
          "prompt": "A slow pan across a foggy harbor at dawn",
      },
      timeout=300,
  )
  ```

  ```json 请求体字段方式 theme={null}
  {
    "model": "deepseek/deepseek-v4-pro",
    "prompt": "A slow pan across a foggy harbor at dawn",
    "client_request_id": "0b8f6a2e-4d1c-4f3a-9e57-1c2d3e4f5a6b"
  }
  ```
</CodeGroup>

请在**发送请求之前**持久化保存这个 id —— 一旦响应没有到达，它就是你找回任务
的唯一凭据。

## 连接中断后找回任务

如果 POST 超时或连接被重置，**不要**立刻认定任务丢失 —— 先查一下：

```bash theme={null}
curl "https://vibetoken.cn/v1/videos/generations?client_request_id=0b8f6a2e-4d1c-4f3a-9e57-1c2d3e4f5a6b" \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx"
```

* **`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 的并发请求是安全的：只会创建一个生成任务，另一个请求会重放
  它。