Source: https://01router.com/zh/docs/callback
Base URL: https://01router.com/api/v1

# 任务回调

传入 callback_url（公网 https 地址），任务成功或失败后我们会把最终的 generation 对象 POST 过去，失败按退避重试最多 5 次，无需轮询。

## 输入参数

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| callback_url | string<uri> | no | 公开 HTTPS 地址，最长 1,000 字符。接收最终任务对象，不允许内网地址。 |  |

## 输出字段

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| id | string | — | 创建任务返回的生成 ID。 |  |
| object | "generation" | — | generation |  |
| model | string | — | 模型目录中的 slug；项目密钥也可使用项目自定义的模型 slug。 |  |
| type | video \| image \| audio \| chat | — |  |  |
| provider | string | — | 可选供应商 slug。不传时自动路由；项目配置可能固定供应商。 |  |
| status | string | — | queued（排队）/ processing（处理中）/ succeeded（成功）/ failed（失败）。成功或失败后停止轮询。 |  |
| input | object | — | 模型专属的输入对象。必填字段、默认值和限制见对应模型文档。 |  |
| outputs | string[] | — | 结果文件 URL 列表；结果未就绪时为空。链接可能过期，请及时下载。 |  |
| error | string \| null | — | 失败时的错误信息，否则为 null。 |  |
| credits | number | — | 该任务扣除的积分，退款后为 0。 |  |
| price_usd | number | — | 该任务的美元价格，退款后为 0。 |  |
| created_at | string | — | ISO 8601 格式的创建时间。 |  |
| completed_at | string \| null | — | ISO 8601 格式的完成时间，进行中为 null。 |  |

## cURL

```bash
curl 'https://01router.com/api/v1/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A red fox running through fresh snow, cinematic"
  },
  "callback_url": "https://your-app.com/webhooks/generation"
}'
```

## Node.js · HMAC-SHA256

```javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is the original request body, before JSON parsing.
const timestamp = request.headers.get('x-gateway-timestamp') ?? '';
const signature = request.headers.get('x-gateway-signature') ?? '';
const expected = 'sha256=' + createHmac('sha256', process.env.API_KEY)
  .update(timestamp + '.' + rawBody).digest('hex');
const received = Buffer.from(signature);
const signed = Buffer.from(expected);
const fresh = /^\d+$/.test(timestamp) &&
  Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const valid = fresh && received.length === signed.length &&
  timingSafeEqual(received, signed);
if (!valid) throw new Error('Invalid callback signature');
```

## 使用说明

- 每次回调都带 X-Gateway-Timestamp 和 X-Gateway-Signature：sha256=HMAC-SHA256(你的 API Key, timestamp + "." + 原始请求体)。可以校验签名，也可以直接再调一次 GET /generations/:id 确认。
- 按任务 ID 幂等处理回调，使用原始请求体校验签名并拒绝过期时间戳。使用登录会话创建的任务可能没有签名，API 集成应使用密钥创建任务。