BYOK 费用与凭证管理

Q: BYOK 用的是自己的 Key，为什么还会返回 402？

BYOK 调用要从 Credits 余额中支付平台服务费。看 error.message：insufficient credit balance 表示余额低于这次调用要预留的服务费，或账户从未充值（error.code 为 balance_missing），充值后恢复；subscription expired; renew to continue 表示账户订阅已过期，续费后恢复。详见模型不可用。

Q: 设置了 Token 限额，调用很快就返回 429，怎么办？

先看限额是不是早期版本保存的。早期版本把「Token 限额（百万）」按 Token 个数保存，当时填写的 10 实际只允许 10 个 Token，第一次调用后就会触顶；现在编辑器按百万 Token 显示，这类历史值会显示成很小的小数，不会自动放大。编辑 BYOK，在「设置限额」中按百万 Token 重新填写后保存，例如 1000 万 Token 填 10。

使用 BYOK 有两笔费用：服务商按你的账户收取上游费用，LYRouter 对每次成功的 BYOK 调用从 Credits 余额扣一笔固定服务费，实际扣除额见「消费明细」。BYOK 列表按凭证统计服务商成本估算和 Token 用量；凭证的替换、启停、排序和限额都在 BYOK 编辑器的「接入凭证」步骤中管理。

费用构成

费用	收取方	在哪里查看
上游 Token 费用（「API 按量计费」）	服务商	服务商账单；LYRouter 的估算见 BYOK 列表和用量分析的「BYOK Token 费用」
Coding Plan 订阅费（「订阅计费」）	服务商	用量分析的「BYOK 订阅费用」，按 BYOK 中填写的金额折算
平台服务费	LYRouter，从 Credits 余额扣除	订阅充值的「消费明细」

平台服务费

何时收取：请求最终由 BYOK 凭证成功完成时收取。BYOK 调用失败不收；BYOK 失败后改由平台凭证完成时，按平台价扣费，不收服务费。
适用范围：「API 按量计费」和「订阅计费」、内置服务商和自定义服务商都收取。
余额要求：网关在发出第一个 BYOK 请求前，先从余额中预留这笔服务费。余额不足以支付时返回 402 insufficient credit balance（error.code 为 insufficient_credit_balance），请求不会发往服务商，也不会改用平台来源；账户从未充值时 error.code 为 balance_missing。在 订阅充值 页面充值后恢复。
订阅到期：账户订阅过期且超过宽限期后，包括 BYOK 在内的所有调用返回 402 subscription expired; renew to continue，见模型不可用。

BYOK 列表中的用量与费用

位置	显示内容
「累计费用」「累计 Token」卡片	所有 BYOK 凭证的累计合计
服务商通道行	「全部费用」「全部 Token」为该通道全部凭证之和；「本月费用」「本月 Token」显示「—」，卡片旁提示「月度统计待接入」
凭证行	「本月费用」「全部费用」「本月 Token」「全部 Token」显示「已用 / 上限」和百分比，未设上限时显示「不限」

费用怎么算：按「模型与费用」中的刊例价 × 折扣，以及输入（缓存未命中）、输入（缓存命中）、输出、显式缓存创建四类 Token 估算的服务商成本，不含平台服务费和订阅费。Token 数为四类之和。
「统计待接入」：该凭证还没有可统计的调用，或其中有调用的费用无法计算，例如「订阅计费」的凭证。
「部分数据加载失败」：部分通道的凭证统计没有取到，合计显示「—」，展开该通道点击重试。
刷新方式：数据在打开或刷新页面时读取，不是实时的。

图 1：BYOK 列表按服务商通道和凭证展示费用、Token 用量与状态。截图为演示数据，点击图片可查看原图。

管理凭证

在列表中点击编辑按钮，打开「接入凭证」步骤：

操作	做法
替换密钥	在「API Key」中输入新密钥。留空表示保留原密钥（提示「留空保持原密钥」）。已保存的密钥只显示脱敏前缀，例如 `sk-demo****`，无法查看明文
停用 / 启用	切换「启用」开关。新添加的凭证保存后均为启用状态，需要停用的，保存后再编辑关闭
调整顺序	在「顺序」列上移、下移，数字小的先尝试
增加凭证	点击添加其他账户凭证
删除凭证	点击行末删除按钮，至少保留一个；要暂停整个通道，在列表中点击停用按钮

所有修改在点击 保存配置 后生效，几秒内同步到网关。替换密钥后用检测或 测试连接 确认新密钥可用。排障时提供凭证备注和脱敏前缀即可，不需要提供完整密钥。

图 2：在「接入凭证」中替换、停用和排序凭证，已有密钥留空即保持不变。截图为演示数据，点击图片可查看原图。

健康状态

新增的凭证保存后自动检测一次，检测方式是读取服务商的模型列表。凭证行的「状态」显示「正常」「检测中」「错误」或「已停用」。
服务商通道行在全部凭证检测失败时显示「错误」，点击可查看异常凭证、失败原因和「最近检测」时间，并可 重新检测 或 检查配置；部分凭证失败时显示「接近限额」，展开通道查看各凭证的状态。
状态只用于提示，不影响选路：显示「错误」的凭证仍会被尝试。确认密钥失效后，及时替换或停用。替换密钥后列表中的状态不会自动更新；通道显示「错误」时，点击它并选择 重新检测。

凭证限额

「API 按量计费」的凭证可以设置限额：在「用量与费用限额」列点击 设置限额，按「费用限额（¥）」和「Token 限额（百万）」分别填写「月度」「累计」上限，留空或填写 0 表示不限。

达到上限时：该凭证在选路时被跳过，网关继续尝试同一通道的下一个凭证、平台凭证和其他通道。所有可用凭证都达到限额时，返回 429 all upstream credentials for this model are rate limited（error.code 为 upstream_quota_exhausted），见429：限流与配额。
计数方式：用量在请求完成后计入，越过上限的那次请求会正常完成；计数有短暂延迟，请给上限留出余量。月度上限每月 1 日重置，累计上限不会重置。
Token 限额的单位：「Token 限额（百万）」按百万 Token 填写，例如 10 表示 1000 万 Token、1.25 表示 125 万 Token。保存后可在凭证行的「本月 Token」中核对上限。
控制服务商花费：需要严格控制服务商侧的花费时，同时在服务商控制台为该账户设置额度上限。

常见问题

列表中的费用与服务商账单对不上，以哪个为准？

答：以服务商账单为准。列表中的费用是按 BYOK 中设置的刊例价和折扣估算的，服务商的实际价格、优惠和计费规则可能不同；平台服务费也不在其中，请在 订阅充值 的「消费明细」中核对。

BYOK 用的是自己的 Key，为什么还会返回 402？

答： BYOK 调用要从 Credits 余额中支付平台服务费。看 error.message：insufficient credit balance 表示余额低于这次调用要预留的服务费，或账户从未充值（error.code 为 balance_missing），充值后恢复；subscription expired; renew to continue 表示账户订阅已过期，续费后恢复。详见模型不可用。

设置了 Token 限额，调用很快就返回 429，怎么办？

答：先看限额是不是早期版本保存的。早期版本把「Token 限额（百万）」按 Token 个数保存，当时填写的 10 实际只允许 10 个 Token，第一次调用后就会触顶；现在编辑器按百万 Token 显示，这类历史值会显示成很小的小数，不会自动放大。编辑 BYOK，在「设置限额」中按百万 Token 重新填写后保存，例如 1000 万 Token 填 10。