# 幂等与限流

> 使用 Idempotency-Key 安全重试，了解每分钟提交限流、进行中任务数上限与请求体大小限制。

## 幂等创建任务

`POST /v1/tasks` 支持可选请求头 `Idempotency-Key`（最长 255 个字符，推荐使用 UUID 或业务订单号）：

- **24 小时内相同 Key + 相同请求体**：以 HTTP `200` 返回原来的任务对象（新建任务是 `201`），不重复建任务、不重复冻结。
- **24 小时内相同 Key + 不同请求体**：返回 HTTP `409`（`idempotency_conflict`）。

```bash
curl -X POST https://api.kerox.ai/v1/tasks \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-a1001-shot-1" \
  -d '{
    "model": "bytedance/seedream-5.5",
    "input": { "prompt": "a quiet coastal lighthouse at dusk", "size": "2K" }
  }'
```
```python
import os
import uuid
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "bytedance/seedream-5.5",
        "input": {"prompt": "a quiet coastal lighthouse at dusk", "size": "2K"},
    },
    timeout=30,
)
print(resp.json())
```
```javascript

const res = await fetch('https://api.kerox.ai/v1/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: 'bytedance/seedream-5.5',
    input: { prompt: 'a quiet coastal lighthouse at dusk', size: '2K' },
  }),
});
console.log(await res.json());
```

## 限流与并发上限

`POST /v1/tasks` 的每个响应都带限流头：

| 响应头 | 含义 |
| --- | --- |
| `x-ratelimit-limit` | 当前账户每分钟允许提交的任务数 |
| `x-ratelimit-remaining` | 当前时间窗口内剩余可提交次数 |
| `x-ratelimit-reset` | 距离窗口重置的秒数 |
| `retry-after` | HTTP `429` `rate_limited` 时附带，建议等待的秒数 |

另一个上限管同时进行中的任务数（`queued` 或 `running`）。超过后 `POST /v1/tasks` 返回 HTTP `429` `concurrency_limited`：等有任务结束后再提交。

上传另有上限：`POST /v1/files` 每个账户每分钟最多 60 次上传，超过后返回 HTTP `429` `rate_limited` 并带 `retry-after`。同一个 IP 地址的提交和上传还有一个更高的每分钟上限。

`GET /v1/account` 会返回任务的这两个上限（`limits.max_per_minute`、`limits.max_concurrent`）和进行中的任务数（`running_tasks`）。

## 体积限制

- **JSON 请求体**：≤ 4 MB
- **内联 base64 data URI**：单次请求合计 ≤ 3 MB（更大文件请改用 `POST /v1/files`）
- **表单直传（multipart）**：≤ 4 MB
- **预签名上传（`/v1/files`）**：≤ 200 MB
- **任务 `metadata` JSON**：≤ 4 KB
