503 budget_pools_disabled；不要改成不走预算池的请求重试。
金额与责任
预算池金额为十进制 USD 字符串，输入最多 8 位小数，输出固定为 8 位小数。JSON number、负数输入、指数表示法、null 和超出精度的值均无效。最大准入金额为90071992.54740991 USD。授权可以为零；credit、debit 和可选的子密钥上限必须为正数。
预算池暴露四个金额：
授权不是您 wallet 剩余余额的镜像。credit 只会增加 A，绝不会减少 C。例如：授权
10、debit 3，再 credit 1，则 A 为 11，C 为 3，R 为 8。把 A 设成 wallet 剩余的 8 会把同一笔消耗扣减两次。
C 和 F 由 Sunra 维护，您无法覆盖它们。把 A 设为低于 C 加 F 会立即暂停预算池，并可能使 R 为负。此前已准入的工作仍按其实际记录的金额结算。增加授权不会自动恢复已暂停的预算池。
LLM 调用在下发之前预留其估算的最大售价。一次原子决策同时检查共享预算池和子密钥的可选上限。外部 debit 与这些 reservation 竞争同一份额度，并立即落账。使可用额度恰好为零的决策是允许的。被拒绝的 debit 不会部分消耗授权，也绝不会产生 LLM 记录或子密钥 receipt。
Media endpoints
媒体访问启用后，预算池子密钥可调用所有多模态队列端点及上传初始化，仍须遵守密钥自身的模型访问限制。通过https://api.sunra.ai 使用 Authorization: Bearer <child secret> 调用：
不入池的 standalone 预算子密钥调用这些路由返回
403 budget_key_route_forbidden。上传初始化不计费，返回 201；使用响应中的签名上传 URL 传输文件。
每次媒体提交与 organization 额度冻结使用同一准入金额。pre_defined 端点按精确价冻结。 对于按使用量结算（post_calculated）的端点，价卡的 freeze_amount 是每次请求的最大冻结额。提交时默认冻结该金额；如果可以按请求估算，则使用不超过 freeze_amount 的估算金额。Seedance 2.5 根据分辨率、时长和是否包含参考视频估算；draft-to-video 使用可用的源草稿信息，信息不可用时回退到固定冻结额。例如，720p、5 秒的 Seedance 2.5 text-to-video 约冻结 $1.41，带参考视频的 reference-to-video 约冻结 $6.86。结算仍按实际用量计费，可能超过估算金额；未使用的冻结额会释放。 见定价 API。这是估价准入，不是花费硬上限：池中已记账金额与在途持有之和超过授权时，池因 liability 暂停，新提交返回 402 budget_pool_paused；需要先 credit 增加授权，再 resume。可选的子密钥 cap_usd 同样只限制估价准入：$1 cap 可先持有 $1、再实收 $2；池总授权足够时仍 active，子密钥 `spent_usd` 记录 $2，下一次提交被拒绝。
402 准入响应中的 estimate_usd 给出该单所需的准入金额。同价的 N 个并发提交在结算释放持有前需要 N 倍可用授权余量；混合端点则需要各单准入金额之和。$0.10 池无法容纳 $1.00 的音频持有；N 个估算金额相同的视频提交需要 N × 每单估算金额的余量；混合请求则累加各单估算金额。实际费用较低时释放差额。失败调用若已收费，即使发票为 VOID 也会记录实收。
x-sunra-call-tag 只在提交 prediction 时校验。配置了 metadata.allowed_tags 的子密钥在提交时必须携带允许的 tag；上传、状态、结果、流与取消不要求 tag。子密钥只能读取或取消自己提交的 request；他人或不存在的 request 均返回 404，流接口也返回 HTTP 404。
关闭或撤销子密钥不会取消在途任务。池子密钥 close 返回 HTTP 200，在发票结算前 body 为 status: "finalizing"，结算后为 closed；终值包含晚到的媒体收费。
/calls 先按数据库 ID 顺序列出 LLM 行，再列出媒体行。cursor 为调用 ID（chatcmpl_ 或 pd_）。open 列表不是快照：cursor 进入媒体段后新增的 LLM 行不会出现在本轮遍历中。完整账本应在 close 后从头读取，并确认 complete: true；calls_count 合计两类调用。媒体 receipt 含 endpoint、非 token 的 usage: { usage_key, usage, unit_amount }、提交 tag 与实际 cost_usd，不含 wire_id。 媒体 usage 缺失字段显式为 null：无 usage 数据的取消单或 charged-VOID 单返回 usage: { usage_key: null, usage: null, unit_amount: null }，close 后保持一致；媒体 receipt 不含 token 计数器。
鉴权与管理
在https://api.sunra.ai/v1 上使用有效的普通 API key 管理预算池和密钥。LLM 调用则在 https://api-llm.sunra.ai/v1 上使用签发的子密钥 secret。预算子密钥和用户 session 不能管理预算池。
management 不可修改，默认为 org：
org：同一 organization 内有效的普通密钥都可以管理该预算池。parent_only：签发父密钥在保持 active 期间管理该预算池。如果该父密钥确定处于 inactive、已撤销、已停用或不存在，同组织内另一把有效的普通密钥可以恢复、读取、暂停和关闭它。父密钥查询失败不授予恢复权限。
404 budget_pool_not_found。管理保护不是 organization 内部额外的保密边界；已有的组织级 completion 访问权限保持不变。
原始父密钥失效后，恢复密钥不能对该预算池执行 debit 或 resume。它仍可以确认历史结果、追加修复用的 credit、暂停和关闭。已确认的 operation 重放保留其原始结果。
在 dashboard 中查看预算池
platform.sunra.ai/dashboard/budget 的 Budget 标签页在 Pools 下列出组织的预算池：ref、状态（暂停时附原因）、已授权与已分配金额、未关闭子密钥数、父密钥。可按搜索词、状态和父密钥筛选。页面只读：暂停、恢复与关闭仍需用普通 API key 通过 API 操作。未开通预算池的组织会看到”未启用”提示。创建与找回预算池
201 和一个 budget_pool 资源。创建身份由 organization、ref 和 expected_generation 构成。以相同的归一化参数重复请求返回 200，并带回同一个预算池 ID 及其当前 snapshot。参数不同则返回 409 budget_pool_conflict。对于全新的创建身份，若 expected_generation 与当前 head 的代不一致，或 head 尚未关闭，则返回 409 budget_pool_generation_mismatch，并附带 details.current_generation 与 details.current_state（不存在 head 时 current_generation 为 "0"，current_state 省略）。ref 必须为 1–256 个字符。
第一个预算池使用 expected_generation: "0"。第 "1" 代关闭后，使用 expected_generation: "1" 创建第 "2" 代。新的一代拥有新的预算池 ID。旧的创建重试始终找回它原本的预算池，不能开启新的一代。每个 organization 与 ref 的组合只能存在一个当前代。
ref 和 state（active、paused 或 closed）筛选条件、1–100 的 limit（默认 100）以及不透明的 after 游标。它按创建时间从新到旧返回 {data, has_more, next_cursor}，因此同一个 ref 的代号是递减的。先应用权限再分页。跟随游标翻页时，请保持筛选条件和调用凭证不变。跨分页的列表不是财务 snapshot。
预算池资源包含 id、organization、ref、generation、version、state、四个金额、management、parent_api_key_id、created_at、last_admitted_at、pause_reason、close_requested_at、closed_at、closed_by_api_key_id 和 open_children。未设置的生命周期时间戳和归因为 null。generation 和 version 是十进制字符串。version 在实际状态变化时递增，恢复后可能跳变；它不是 wallet 事件的水位线。
签发 turn 密钥
ref 为必填，用于标识预算池内的一张逻辑 ticket。已有的 models、metadata 和 call tag 限制仍然适用。可以额外提供正数的 cap_usd，作为针对该子密钥的第二重上限；省略时该密钥只受共享预算池约束。未设置时子密钥资源不返回 cap_usd，并包含 pool_id 和 pool_generation。
首次成功 mint 返回 201 和一个 secret。相同的 pool/ref 和相同参数返回 200，带回同一个子密钥且不含 secret。参数不同则返回 409 budget_key_mint_conflict。系统只存储 secret 的哈希值。如果在保存 secret 之前丢失了首次 response，请找回子密钥 ID，关闭该 ticket 并结清其账目。不要复用它的 ref 创建另一张 ticket，也不要指望找回 secret。
status: "closed"，再把它的 receipt 视为最终结果。
入池子密钥的 close 返回 200，状态为 finalizing 或 closed；请检查资源状态。Receipt 仍保持 version 1、调用标识、封存的已付金额和完整分页。请取回全部调用分页，并将其已付金额总和与子密钥的最终支出核对。外部 operation 不计入这些 receipt。把该 receipt 记入您的 wallet 时，不得再次对预算池执行 debit。
每张 ticket 只有一个 secret。本次发布不支持延长到期时间，也不支持替换既有 ticket 的 secret。
变更授权或暂停准入
If-Match 中带上先前 snapshot 的 version，这样过期的 wallet 更新就不会覆盖并发的 credit。version 过期返回 409 budget_pool_version_conflict。
If-Match。读取、结算和 credit 仍然可用。
409 budget_mutation_conflict。重放不会递增 version。
预算池在连续 24 小时没有成功的 LLM 准入或外部 debit 后暂停，创建满七天后也会暂停。读取、失败的准入、credit 和 PATCH 都不会延长它的活跃窗口。到期永远不会自动关闭预算池。超龄的预算池必须结清，并用新的一代替换。
Debit、credit 与找回 operation
201；重放已应用的 operation 返回 200。请在发起请求之前先持久化您的 operation ID。在对应的 debit 确认 applied 之前，不要启动外部工作。该外部工作后续成功不会再次对本预算池执行 debit。
在确认充值或退款后，使用 type: "credit" 授予更多授权。credit 可以带上 related_operation_id，指向同一预算池中已应用的 debit。该关联仅用于审计；Sunra 不实现您的订单或退款状态机。reason 为可选，最多 256 个字符，对授权没有影响。operation ID 是 1–128 个字符的不透明字符串。
status（pending、applied 或 rejected）、时间戳、result_version 以及该决策对应的预算池 snapshot。applied 和 rejected 的结果不可变。即使后续 operation 改变了预算池，重放仍返回原始决策的 snapshot。金额在归一化后比较；type、generation、reason 和关联 ID 也参与冲突检测。
存储超时且决策未确定时可能返回 202 pending。请查询或重试同一个 ID。404 只表示没有找到持久化的意图，并不意味着可以换用新 ID。被拒绝的 debit 在后续 credit 之后仍然是 rejected；真正的新尝试需要一个新的、已持久化的 operation ID。同一 ID 下提交不同请求返回 409 budget_operation_conflict。
operation 列表按创建时间正序排列，使用绑定该预算池的不透明游标，分页大小同样为 1–100。请单独轮询 pending 的 ID，因为分页扫描不是状态变化的推送流。
关闭预算池
409 budget_pool_children_open 拒绝，此时不产生任何关闭副作用。force: true 会先停止预算池准入，再通过子密钥既有的 finalization 路径关闭它们，包括 mint response 仍在找回中的子密钥。
关闭完成返回 200 closed。如果已接受的责任或成员归属结果仍未确定，则返回 202 paused 并设置 close_requested_at。请重试同一个 close 操作。关闭请求不可逆：新的 mint、resume、PATCH、debit 和 credit 都会被阻止，但已接受的工作仍可继续结算。关闭不会退还 R，因为从未有资金转入该预算池。
已关闭的预算池永不重开。它们的 snapshot、operation、子密钥记录和 receipt 仍可供审计。旧 ID 和旧代不能修改新的一代。已确认的历史 operation 在关闭后仍可重放。
可入池模型与上限转换
LLM 调用中，入池子密钥使用显式的模型 allowlist：模型按实测的输出上限行为准入；对于下文记录的小幅溢出，预留时增加固定的 completion token 开销。未列入的模型返回400 model_not_poolable，其中包括六个推理型 Grok 模型 grok-4.20、grok-4.3、grok-4.5、grok-4.6、grok-4.7 和 grok-build-0.1。普通密钥和不入池的子密钥保持原有行为。
以下八个模型需要 Chat Completions 转换：
- Ark：
doubao-seed-2.1-pro、doubao-seed-2.1-turbo、doubao-seed-evolving、glm-5.2。 - DashScope：
qwen3.7-flash、qwen3.7-plus、qwen3.7-max、qwen3.8-max。
max_completion_tokens 发送，并从上游副本中移除 max_tokens。该上限包含推理输出。客户端 body、推理意图和 reservation 公式保持不变。这八个模型上的入池 Responses 和 Messages 请求返回 400 invalid_input，因为该转换未在这两种格式上验证过。
原生上限的 76 个模型 ID 如下（连同上述八个需转换的 ID，共 84 个可入池 chat 模型）：
claude-fable-5claude-fable-5-1claude-opus-4-7claude-opus-4-8claude-opus-5claude-opus-5-5claude-sonnet-5claude-sonnet-5-5claude-haiku-5-5gpt-5.4-proclaude-opus-4-6-awsclaude-opus-4-7-awsclaude-opus-4-8-awsclaude-sonnet-4-6-awsclaude-opus-4-6-reverseclaude-sonnet-4-6-reverseclaude-opus-4-6claude-opus-4-6-openrouterclaude-sonnet-4-6claude-sonnet-4-6-openrouterdeepseek-flashdeepseek-v4-flashdeepseek-v4-flash-vision-expdeepseek-v4-progemini-2.5-flashgemini-2.5-flash-gcpgemini-2.5-flash-openroutergemini-2.5-progemini-2.5-pro-gcpgemini-2.5-pro-openroutergemini-3.1-flash-lite-previewgemini-3.1-pro-previewgemini-3.1-pro-preview-gcpgemini-3.1-pro-preview-openroutergemini-3.5-flashgemini-3.5-flash-gcpgemini-3.5-flash-litegemini-3.6-flashgemini-3.7-flashgemini-3.8-flashgemini-4-argongemini-4-argon-gcp（gemini-4-argon的路由组，不是独立公开 ID）glm-5glm-5-turboglm-5.3glm-5.3-flashgpt-4o-minigpt-5-minigpt-5-nanogpt-5.3-codexgpt-5.4gpt-5.5gpt-5.6-lunagpt-5.6-solgpt-5.6-terragpt-6-astragpt-6-lunagpt-6-solgpt-6.1-solgpt-oss-120bgrok-4.20-non-reasoningkimi-k2.6kimi-k2.7-codekimi-k2.7-code-highspeedkimi-k3longcat-2.0minimax-m2-herminimax-m2.1minimax-m2.5muse-spark-1.1muse-spark-1.2muse-wondero3o4-miniqwen3.5-plusseed-2.0-liteseed-2.0-mini
-reverse 和 -relay 别名准入，因为它们在 Anthropic 格式的上游上提供相同的 Claude 模型。旧的 -aws 别名可能退化到未 pin 的默认路由。只有遵循相同上限规则的合格上游路由才能执行；解析到不合格路由的请求会 fail closed，返回 400 model_not_poolable。
文本 /v1/embeddings 请求（包括 gemini-embedding-2）保持仅按 prompt 预留，不需要 completion allowlist 条目。子密钥仍禁止 native/media embeddings。minimax-m2.7 已下架。
这些是公共模型解析之后的精确 released 模型名，不是按家族或前缀授权。新增模型和别名必须先通过计费输出上限验收检查才能加入。grok-4.20-non-reasoning 是单独实测的原生条目；它不代表任何推理型 Grok 同族模型获得授权。
使用 Chat Completions 时，请提供正整数的 max_tokens 或 max_completion_tokens。两者同时提供且取值不同时无效。原生 Responses 和 Messages 在可用时保留已有的输出上限回退。入池子密钥对任何 previous_response_id 返回 400 invalid_input；隐藏的历史上下文无法计入准入估算。预算子密钥的推理预算校验在预算池 reservation 之前执行，使用的是叠加 reservation 开销之前的原始输出上限。已有的子密钥输出参数校验、单 completion 限制、模型限制和关闭 thinking 的规则继续生效。
错误
错误沿用已有的 v2error envelope。请检查 error.details.reason 和 retryable。HTTP 402 使用粗粒度 code INSUFFICIENT_CREDIT，HTTP 503 使用 INTERNAL_ERROR，其他预算错误使用 HTTP_EXCEPTION。
budget_exhausted 的 details 包含同一次原子决策的 authorized_usd、committed_usd、in_flight_usd 和 estimate_usd，以及 scope: pool|child。因子密钥上限被拒时还包含 spent_usd、reserved_usd 和 cap_usd。blocking: in_flight 表示未释放的 reservation 是阻塞原因，此时 retryable 为 true。blocking: committed 表示仅等待 reservation 释放无法让该请求通过。operation 被拒时包含 operation_id。
恢复与限制
预算池的执行是临时的：空闲超时为 24 小时，最长存续七天。它不是永久 wallet。您的应用负责协调 wallet 更新、换代、外部工作，以及哪些 wallet 事件已经计入新预算池的初始授权。Sunra 不实现资金桶、订阅、订单状态或 wallet 欠款补偿。wallet 侧的补偿不会自动授予新的预算池授权。 受支持模型的契约所针对的输出上限涵盖全部计费输出，包括已声明的推理部分。准入仍使用已有的保守 prompt 字节估算，并预留完整的输出上限。每个识别到的图片、音频、视频或文档 part 计入 8,192 个输入 token：存在专门的媒体价格时使用该价格，否则把该额度折入 prompt 价格。这些输入约定可能拒绝实际成本更低的请求。可用金额为很小的正数并不保证准入；请调低合适的输出上限，或等待在途工作结算。实际付费金额会如实保留，不会截断到授权额度。有意调低授权可能使此前已接受的责任高于新的授权额度。 严格覆盖实际成本需要对 provider 行为和输入/媒体计费口径做验收验证。qwen3.5-plus 的初始验收记录显示：请求上限为 64 时计费输出为 66 个 token。按 9 月 19 日的准入决定，该模型的预算池 reservation 按准入上限加两个 completion token 计价（64 预留 66）。发往上游的上限和客户端 body 保持不变。自 2026 年 10 月 14 日起，muse-wonder、muse-spark-1.1 和 muse-spark-1.2 按请求上限加 64 个 completion token 预留；客户端 body 和发往上游的上限不变，实付仍按真实 usage 结算。这一固定预留覆盖已实测的溢出，并非 provider 对每次请求的保证。除上述 Muse 模型和 qwen3.5-plus 外，其他模型的 completion 开销为零。本地测试验证的是这一 reservation 行为，而不是新的线上 provider 实测。
Redis 状态丢失会停止新的支出。恢复流程会从持久化记录中重建已付支出、已应用的外部 operation 和未释放的 completion reservation，然后让预算池保持 paused，等待显式 resume。未结的账目条目即使在请求 lease 过期后仍保留其财务责任。只有已过期且没有对应 completion 记录的 reservation，才能作为未下发的孤儿回收。
如果在外部 operation 或生命周期决策仍等待持久化确认时 Redis 消失，其确切决策可能无从得知。恢复期间，来自旧 epoch 的 operation 在创建后 60 秒内保持 pending；若此后仍没有持久化的 applied 决策，恢复流程会以 decision_unavailable 拒绝它，绝不会盲目地再次 debit 或 credit。用同一 ID 查询或重试即可取回这条不可变的拒绝结果；真正的新尝试需要新的、已持久化的 operation ID。超时或处于 finalizing 的 close 都不能证明费用为零。如果恢复长期处于 pending，请带上预算池 ID 和 operation ID 联系 Sunra。
客户端断连沿用已有的取消和持久化结算证据路径。Receipt 描述的是持久化的 Sunra 计费记录，不会臆造从未记录过的用量。新的 provider 路由需要重新做边界验证；已实测的模型矩阵并不保证 provider 未来的实现会保持今天的行为。
运维可以单独停用新的预算池准入，而不影响读取、结算、credit 修复和关闭。启用该功能之前，所有 auth 和网关实例都必须能够识别入池凭证。回滚必须先停止准入并结清既有的财务责任；同时必须保留用于读取留存 receipt 和 operation 的读接口。
部署开关为 BUDGET_POOLS_ENABLED（默认 false）、BUDGET_POOLS_ORG_ALLOWLIST（逗号分隔的 organization ID；为空表示不授予任何组织）和 BUDGET_POOLS_ADMISSION_ENABLED（设为 false 可停止新的准入；否则在前两个开关允许的前提下启用）。auth 和 apiv1 需要配置相同的开关。这些开关关闭时，已有的不入池凭证保持原有契约。