DEVELOPER GUIDE
AI API 中转站怎么选：先看接口，再看管理能力
选择 AI API 网关不能只比较一个模型的临时价格。对真实项目而言，接口兼容性、密钥安全、用量记录、错误信息和长期维护成本同样重要。
接口是否清晰
基础地址、鉴权方式、模型 ID 和错误格式应有明确说明。
账单是否可核对
调用时间、模型、Token 用量和费用记录应能相互对应。
密钥是否可管理
不同项目应使用不同密钥，并支持独立撤销和更换。
1. 检查兼容方式
很多 AI 客户端支持 OpenAI 兼容协议，但“兼容”不代表所有扩展参数都完全相同。接入前应确认请求路径、Authorization 头、流式响应、工具调用和错误返回是否符合当前项目的需求。最稳妥的方法是先使用最小请求验证，再逐步加入流式输出、结构化响应或工具参数。
如果项目已经使用支持自定义 Base URL 的 SDK，迁移通常只需要调整基础地址、API 密钥和模型 ID。黑洞中转站提供了可直接核对的兼容接口示例。
2. 核对计费与记录
价格只是成本的一部分。合格的 AI API 中转站还应提供可查询的调用记录，让开发者知道某次请求使用了哪个模型、产生多少用量、何时发生以及最终是否成功。出现费用疑问时，有记录才能定位具体请求，而不是只能比较账户余额前后的差额。
上线前建议建立一组固定测试请求，记录响应和用量。更换模型或客户端版本后再次执行，可以快速发现参数、计费或输出变化。
3. 保护 API 密钥
API 密钥相当于项目凭证。不要把它硬编码在网页 JavaScript、浏览器插件公开配置或 Git 仓库中。服务端项目应通过环境变量或密钥管理服务加载；本地工具应使用操作系统权限受控的配置文件。
- 为开发、测试和生产环境分别创建密钥。
- 不同项目不要长期共用同一个密钥。
- 密钥疑似泄露时立即撤销，而不是只删除代码中的字符串。
- 日志中不要记录完整 Authorization 请求头。
4. 关注可观测性
真实业务不可避免会遇到超时、限流、余额不足、模型不可用或参数错误。平台是否提供明确的 HTTP 状态码和错误消息，直接决定故障定位速度。客户端也应设置合理的连接超时、总超时和有限次数重试，避免一次故障放大成请求堆积。
不要对所有错误无限重试。鉴权失败、参数错误或余额问题需要人工处理，重复请求只会增加噪声和成本。