客户端配置
只要客户端支持自定义 OpenAI Base URL，通常都可以按统一方式接入牛API：一个 Base URL、一个专用 Key、一个真实模型 ID。
通用步骤只代表接入结构，不代表该客户端已通过牛API验证。各客户端的验证状态以兼容性矩阵为准。
接入方式总览
| 客户端类型 | 配置方式 | 说明 |
|---|---|---|
| Cherry Studio、NextChat、Open WebUI、ChatBox 等对话客户端 | 新增 OpenAI Compatible 或自定义 OpenAI 服务商，填写 Base URL 和 API Key | 模型列表不一定能自动拉取，通常需要手动添加模型 ID |
| OpenAI SDK（Python / JavaScript） | 设置 base_url / baseURL，Key 从环境变量读取 | 服务端专用；浏览器前端不得保存长期 Key |
| Codex、Claude Code 等编程 Agent | 先确认工具使用的协议、模型 ID、配置文件位置和本地代理设置，再单独配置 | 见 Codex 与 Claude Code 独立页面 |
| 团队与自动化任务 | 按项目、成员、环境拆分 Key，分别设置额度 | 通过用量记录定位异常消耗，便于单独撤销 |
通用配置步骤
- 在客户端新增 OpenAI Compatible（或自定义 OpenAI）服务商；
- Base URL 填写
https://api.reniuniu.win/v1，注意不要重复或遗漏/v1； - 填写该客户端专用的牛API Key，不要多个客户端共用一个 Key；
- 手动添加控制台展示的真实模型 ID；不同供应商的模型 ID 不要混用；
- 并发设为
1，发送测试提示词请只回复：牛API连接正常，再核对控制台用量。
OpenAI Base URL
https://api.reniuniu.win/v1认证方式
Authorization: Bearer YOUR_API_KEY认证细节
客户端输入框只要求 “API Key” 时，只填写 Key 本身，不要手动添加 Bearer 前缀。只有自行构造完整 HTTP 请求头时才使用 Authorization: Bearer YOUR_API_KEY。
SDK 使用要点
- Key 用环境变量（如
NIUAPI_API_KEY）保存，不写进源码、不提交仓库； - 浏览器前端不得直接保存或发送长期有效的 API Key；网页调用应经过你自己的后端转发；
- 先用最小非流式请求确认认证、模型名和网络，再开启流式与工具调用。
Python 与 JavaScript 最小示例见接口地址 · 通用 SDK。
团队与多环境使用
- 按项目拆分：每个项目独立 Key，异常消耗可以快速定位和撤销；
- 按成员拆分：团队成员不共用长期 Key，离职或权限变更时只撤销对应 Key；
- 按环境拆分：开发、测试、生产不混用同一个 Key；
- 设置限制：控制台支持时，为每个 Key 配置额度和有效期，降低泄露后的损失。
多人共享同一 Key 会让用量归属、权限回收和泄露排查变得困难，也会放大并发冲突（见并发与限速）。
核对用量
排查异常消耗时，优先按以下维度在控制台对照：
- Key：确认消耗来自哪个专用 Key；
- 模型：确认哪个模型产生了主要 Token；
- 日期与时间：与本地操作时间对齐；
- 费用与请求 ID：与余额变化和工单信息对应。
实际筛选字段以控制台实测为准。
常见问题
- 401：Key 不完整、失效或环境变量未生效；重新复制或创建专用 Key；
- 404：Base URL 拼接错误或模型 ID 写错；逐字核对控制台模型 ID；
- 402：余额或 Key 额度不足；先检查控制台余额再充值；
- 429：并发过高；降到
1并退避重试； - 流式中断：先用短提示词复现，再检查本地代理与网络切换。
完整排查流程见常见错误。