BYOK（自带密钥）
BYOK（Bring Your Own Key）允许用户使用自己的上游 API Key 调用模型，平台仅做路由转发和代理，请求成功时不扣平台额度。
适用场景
- 已有自己的 OpenAI、Anthropic 或其他兼容服务商的 API Key
- 想通过统一入口管理多个上游的模型调用
- 调用平台目录中没有的模型（自定义模型）
- 需要利用平台的上游池路由能力，但使用自己的额度
配置凭证
登录控制台后在 BYOK 页面管理凭证：
- 选择 Provider（OpenAI、Anthropic、DeepSeek、Moonshot、Zhipu 等内置模板，或自定义）
- 填写 Base URL 和 API Key
- 选择支持的协议形态（Chat Completions / Messages / Responses）
- 设置模型快照（可选的允许模型白名单，为空则允许所有模型）
- 开启/关闭回落开关（失败后是否回落官方渠道）
凭证数量
每用户最多 10 条凭证，按配置顺序循环尝试。
调用方式
方式一：自动优先
不传 X-Shotject-Channel 请求头。系统自动检测是否有匹配当前模型的 BYOK 凭证：
- 有 → 自动走 BYOK
- 无 → 自动走官方渠道
方式二：显式指定
X-Shotject-Channel: byok— 强制走 BYOK，失败后按回落开关处理X-Shotject-Channel: official— 强制走官方渠道，跳过 BYOK 检测
回落行为
BYOK 失败后，如果该模型在平台目录中且余额充足，允许回落官方渠道。回落成功后按官方价格扣费，响应头中会包含 X-Shotject-Fallback: true。
回落开关可在每条凭证中独立控制。
计费规则
| 场景 | 是否扣费 |
|---|---|
| BYOK 成功 | 不扣费（CallSource = Byok，Quota = 0） |
| BYOK 失败后回落官方成功 | 按官方价格扣费（CallSource = ByokFallback） |
| BYOK 失败且无回落 | 不扣费 |
注意事项
- BYOK 凭证中的 API Key 会被加密存储，列表页只显示前缀。
- 平台对用户提供的 Base URL 做 SSRF 防护（禁止内网地址、环回地址等）。
- BYOK 不检查平台套餐模型目录，但 API Key 自身白名单仍是硬边界。
- 站内 Chat 和智能体默认 Key 不走 BYOK。