API 文档接入指南
任务回调
传入 callback_url(公网 https 地址),任务成功或失败后我们会把最终的 generation 对象 POST 过去,失败按退避重试最多 5 次,无需轮询。
请求
cURL
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
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');输入参数
JSON 请求体callback_urlstring<uri>可选公开 HTTPS 地址,最长 1,000 字符。接收最终任务对象,不允许内网地址。
输出字段
idstring创建任务返回的生成 ID。
object"generation"generation
modelstring模型目录中的 slug;项目密钥也可使用项目自定义的模型 slug。
typevideo | image | audio | chatproviderstring可选供应商 slug。不传时自动路由;项目配置可能固定供应商。
statusstringqueued(排队)/ processing(处理中)/ succeeded(成功)/ failed(失败)。成功或失败后停止轮询。
inputobject模型专属的输入对象。必填字段、默认值和限制见对应模型文档。
outputsstring[]结果文件 URL 列表;结果未就绪时为空。链接可能过期,请及时下载。
errorstring | null失败时的错误信息,否则为 null。
creditsnumber该任务扣除的积分,退款后为 0。
price_usdnumber该任务的美元价格,退款后为 0。
created_atstringISO 8601 格式的创建时间。
completed_atstring | nullISO 8601 格式的完成时间,进行中为 null。
使用说明
- 每次回调都带 X-Gateway-Timestamp 和 X-Gateway-Signature:sha256=HMAC-SHA256(你的 API Key, timestamp + "." + 原始请求体)。可以校验签名,也可以直接再调一次 GET /generations/:id 确认。
- 按任务 ID 幂等处理回调,使用原始请求体校验签名并拒绝过期时间戳。使用登录会话创建的任务可能没有签名,API 集成应使用密钥创建任务。
给 AI 使用
把文档索引或完整接口文档交给 AI 编程助手,包含实时模型参数。