Bambuk 计费与配额
理解接口授权、套餐额度、限流和模型用量。
调用前的检查
调用模型接口需要有效的开发者账号、有效订阅以及剩余额度。AppKey 还需绑定对应接口和订阅；拥有 Key 不等于拥有所有模型的调用权。
接口可以处于停用状态。文档仍可阅读，但调用会失败，平台不会因为文档发布就自动赠送额度。
当前计费方式
Bambuk 内置模型目录初始配置为按次计费 per_call，价格由运营者在后台配置。初始占位价格不代表正式免费政策，正式使用前请查看控制台资源包说明。
- 成功的独立 API 调用按各自的计费配置记录使用量。
- OCR 后再调用翻译是两个模型请求。
- HTTP 200 但模型业务返回失败的请求，在网关验证失败后不扣模型调用额度。
- 超时或网络中断可能发生在模型已执行之后；应通过使用记录核对结果，不盲目自动重试。
Token 的边界
按 token 的接口必须配置模型返回的真实用量字段，例如 usage.total_tokens（输入加输出）或 usage.input_tokens（只计输入），计费口径由运营者明确选择。模型必须实际返回该字段；缺失、负数、小数或无法解析的用量会导致结算失败，不会把未知用量视为 0，也不会用字符估算扣费。模型明确返回 0 时记录 0，不强行提高到最低扣量。
套餐可混合包含按次接口和按 token 接口，各接口额度独立。-1 表示不限量，0 表示不包含；额度必须为整数。单次 token 上限按实际计费字段检查，超出上限的结果不交付且不扣额度，模型可能已经执行，因此应同时在模型侧限制生成长度。
套餐与费用试算
套餐按接口能力独立定价，购买前可调用 POST /api/v1/billing/packages/quote 传入多个 package_ids，取得逐项明细和总价：
{"package_ids":["套餐 UUID 1","套餐 UUID 2"]}返回的 total_price_cents 使用人民币分，items 包含每个套餐的价格、有效期和配额。当前支付采用“一套餐一订单”，每个接口套餐独立发放额度和计算有效期，便于支付回调、退款和额度结算逐单幂等处理。
管理端和开发者套餐中心均提供用量计算器：
| 计费方式 | 套餐消耗 | 接口参考费用 |
|---|---|---|
| 按次 | 成功调用次数 | 次数 × 每次单价 |
| 按 token | 每次实际 token 累加 | token 总量 × 每 token 单价 |
单价单位是分，展示人民币时除以 100。接口参考费用用于预算，套餐售价是购买套餐的独立价格；消耗套餐额度时不会额外按参考费用再扣一次现金。试算不创建订单。
订阅在购买时保存总额度与单次 token 上限，之后编辑套餐只影响新购买。已用额度由该订阅的原始额度减去剩余额度得到，不会把其他套餐的用量重复扣除。不限量订阅不展示推算的已用额度，请查看调用记录。
已有套餐引用的接口不能直接切换计费单位，需要创建独立接口，避免把 100 次误解为 100 token。上线前既有订阅没有历史快照，只能按迁移时已知套餐额度与余额回填，无法还原过去的套餐修订。
结算与重试
正式网关在同一个数据库事务中锁定订阅、扣减额度并记录使用量，失败时整体回滚。费用在 PostgreSQL 中用十进制计算，存储精度为小数点后 8 位分。同一个服务端请求标识重复执行结算不会再次扣减，并发请求不会把套餐扣成负数。
客户端重新发送请求会生成新的服务端请求标识，仍是一次新的模型调用；这不是 HTTP 响应缓存或请求幂等重放。超时后请先核对调用记录。
限流
限流和套餐配额是不同约束。即使还有剩余额度，请求过快也可能返回 429 RATE_LIMIT_EXCEEDED。减少并发并加入有上限的等待，不在失败时立即递归重试。
具体 QPS、并发、上传大小和有效期以当前部署配置为准，静态文档不替代控制台中的实时规则。
开发者实例与用量归属
一个开发者可以创建多个应用实例，例如生产、测试、移动端和内部服务。套餐额度属于开发者账户，由该开发者的所有实例共享；实例不会各自复制一份套餐额度，也不会因为创建多个实例增加总额度。
每次成功调用同时记录开发者、实例（应用）和模型能力三层信息：
| 维度 | 用途 | 是否单独扣额度 |
|---|---|---|
| 开发者 | 套餐余额、支付、总额度 | 是，唯一扣减主体 |
| 实例 / 应用 | 生产与测试分账、调用来源、密钥管理 | 否，共享开发者余额 |
| 模型能力 | 翻译、语音识别、图文识别、语音合成的独立统计 | 按接口计费规则扣减 |
按次接口每次成功请求扣 1 次；按 token 接口扣模型返回的实际 token；按时长接口扣实际音频秒数。OCR、ASR、TTS 和多语言翻译分别统计，但都从开发者当前有效订阅中扣减。实例用量用于报表和限额管理，不会重复扣减同一笔套餐额度。
建议为生产实例和测试实例分别创建应用，在调用记录中按实例筛选。测试实例消耗的仍是开发者共享额度；如果需要团队或项目之间完全隔离，应创建不同开发者账号或后续配置独立订阅，而不是复制 AppKey。