UniRouteUniRoute

多模态计费、恢复与错误处理

USD 报价与扣费、共享 Key 额度、未知状态和接口错误

计费、恢复与错误处理

报价、钱包与 Key 限额

先 POST /v1/media/quote，检查 currency: "USD"、policy_version: "usd-wallet-v1" 和精确字符串 quoted_usd，再把这个金额传为 max_cost_usd。当前 quote 是整个任务的报价，目录中的单位价格仅帮助理解，视频可能按秒计费。

账户 USD 钱包承担实际扣费，Key 的消费限额是额外的预算控制。LLM、图片、视频、音乐共享同一 Key 的总额及时间窗口额度，尚未结算的任务也会占用余量。即使 Key 没有总限额，实际调用仍然要从账户钱包支付。

任务的 billing 包含 quoted_usd、held_usd、charged_usd、released_usd 和 state。占用不是实际扣费，释放不是新的充值。以 charged_usd 和 Console 实际账单核对最终费用。

状态下一步
held已占用预算，继续查询同一任务
settling正在结算，继续查询，不创建替代任务
charged已实际扣费；生成也成功后可下载
released已释放；检查生成状态与账单，停止此示例
released_unknown钱包占用可能释放，但上游结果和最终费用仍未知；保留任务 ID 和预算义务，查询或联系支持

生成 success 与结算 charged 是两个条件，不能只看生成成功就宣布全流程完成。后续确认的费用可能在未知状态之后出现。

查询真实消费

GET /v1/usage 返回原始 JSON，没有媒体接口的 data 包装。下面只列出相关字段，其他响应字段可能同时存在。

带总额度的 Key 示例：

{"mode":"quota_limited","quota":{"limit":1,"used":0.1396,"remaining":0.8604}}

没有总额度的 Key 示例：

{"mode":"unrestricted","usage":{"total":{"cost":0.1,"actual_cost":0.15}}}

实际消费优先读取 quota.used；没有总额度时读取 usage.total.actual_cost。仅有时间窗口限制的 Key 也可能是 quota_limited 但没有 quota，此时读取 actual_cost。usage.total.cost 是费率前参考金额，不是实际扣费；旧 balance 字段也不是账户 USD 钱包余额。钱包余额以 Console 为准。

保存调用前后用量，再核对本次各任务 charged_usd 合计。相同 Key 的其他并发 LLM 或媒体调用也会计入总用量增量，所以隔离本次调用或按任务 ID 查账，不能把全部增量默认归给本次任务。

幂等与中断恢复

创建前保存请求体与 Idempotency-Key。成功收到 HTTP 202 后立即保存任务 ID。相同 Key、相同幂等键、完全相同请求体的重放应返回同一 ID；换 prompt、option 或 max_cost_usd 都不是相同请求。

已知 ID：使用 GET /v1/media/tasks/{task_id} 恢复；不要再次创建。未知 POST 结果且没有 ID：保留原请求和幂等键，查询 GET /v1/media/tasks?limit=20 的本 Key 历史并按 next_cursor 翻页，或联系支持确认。不要自动重试未知 POST，也不要删除状态文件、换幂等键猜测重建。独立客户端会在网络请求前持久保存 sent，收到 ID 后立即持久保存，未知结果重启后在任何 API 调用前停止。

限流和错误

每个 Key 的媒体请求最多 120 次/分钟，目录、询价、查询和历史都计入；创建 POST 最多 10 次/分钟，幂等重放也计入创建请求。并发未完成任务最多每 Key 10 个、每用户 30 个。客户端按顺序创建，普通请求间隔至少 0.7 秒，创建/重放间隔至少 7 秒，轮询间隔 5 秒。

HTTP常见原因与处理
400请求字段、选项或成本上限不合法；确认当前 quote 和精确 USD 字符串
401Key 无效、过期或已撤销；检查原 Key，不在日志中暴露密钥
403Key 类型/限制不符合要求或内容审查拒绝；检查统一 Key 与输入
404任务不存在或属于其他 Key；使用创建时的同一 Key
402 / 403钱包或 Key 额度不足；查看 Console 的实际资金与限额
409幂等请求体冲突或并发限制；保留原任务，不盲目重新创建
429请求频率过高；遵循 Retry-After 降低频率，未知创建仍不自动重发
503当前服务或结算能力不可用；保存状态，已有 ID 继续查询，未知 POST 先确认结果

媒体错误返回 HTTP 状态和 {code,message,reason,data:null}。保留状态码、任务 ID、原幂等键供支持定位，不公开 Key 或私有上游细节。公共下载请求完全独立，不发送 Bearer，不允许降级到 HTTP。