TheRouter v2.0：统一异步媒体平台，覆盖图片 / 音频 / 视频

TheRouter v2.0 上线统一的异步媒体生成范式。任何超过 CDN 边缘超时的图像 / 音频 / 视频任务，都可以走 Job 流程 — 一套接口，三种模态；同步面零行为变化。

变化

在媒体接口上附加 ?async=true，TheRouter 立即返回 HTTP 202 与轮询 URL：

curl -X POST https://api.therouter.ai/v1/images/generations?async=true \
  -H "Authorization: Bearer ***" \
  -d '{"model":"openai/gpt-image-2","prompt":"京都的日落"}'

# 202 Accepted
# {
#   "id": "img_01J...",
#   "polling_url": "https://api.therouter.ai/v1/jobs/img_01J...",
#   "status": "queued",
#   "expires_at": "2026-05-15T12:00:00Z",
#   "model": "openai/gpt-image-2"
# }

轮询 /v1/jobs/:id 直到 status: succeeded，再从 unsigned_urls[] 读取存放在 S3 的产物。相同流程适用于 /v1/videos、/v1/audio/speech、 /v1/audio/transcriptions。

为什么做这件事

直接触发是一次真实计费事故：一笔长任务图像生成被 CloudFront 524 超时切断，但 上游已经实际消费了额度 — 客户付了钱却没拿到结果。异步流程把客户的 HTTP 连接 与上游生命周期彻底解耦。

新计费模型有三条硬约束：

1. 202 时预留额度 — 任务被接收的瞬间锁定额度，不结算。
2. 上游完成时结算 — 上游真正成功返回，才记录实际成本。
3. 仅当上游失败时退款 — 上游报错才释放预留；客户断网、关浏览器、连接超时 等不会触发误退，因为上游已经实际消费了额度。

成本与存储约束

产物在 S3 中 30 天自动过期。基于 tenants.tier 的租户级存储配额和跨模态 并发上限，防止单账号失控。v1.x 同步接口完全不变，未带 ?async=true 的请求 继续走原有路径。

Sora 2 与 webhook

POST /v1/videos 已重新启用。Sora 2 配置在 feature flag 后，等待 OpenAI 组织验证后开放。任务完成的 webhook 推送 是下一阶段优先项 — 当前仅支持 轮询。

上手

• Guide：异步媒体
• 参考：Jobs API
• 参考：Audio API