One API 是一套开源的 LLM API 管理与分发系统,调用格式与 OpenAI 完全一致:把客户端的 API Base 换成「部署地址 + /v1」,API Key 换成令牌页生成的 sk- 令牌即可。仓库在 github.com/songquanpeng/one-api,最新正式版 v0.6.10。下文按部署、接上游、建令牌、发请求的顺序拆开讲,并附端点清单与报错对照表。
One API 是什么,调用前要准备什么
One API 用 Go 写成,以单个可执行文件或 Docker 镜像交付,MIT 协议开源。它把多家厂商的模型接口收拢到一套 OpenAI 格式之下,对下游只暴露一个地址、一组密钥。截至本文核实时间(2026 年 9 月),仓库 github.com/songquanpeng/one-api 的 Star 数约 3.7 万,最新正式版本 v0.6.10 发布于 2025 年 2 月 2 日。
搜 oneapi 还会撞上 Intel oneAPI,那是面向异构计算的编程工具套件,含 DPC++、SYCL 等组件,与大模型 API 网关无关。分辨看上下文,出现「渠道」「令牌」「中继」字样的才是本文讲的这个。
- 至少一个上游 API Key:OpenAI、Azure、Anthropic,或国内的通义、文心、混元、DeepSeek。
- 一个能改接口地址的客户端:OpenAI 官方 SDK、ChatGPT Next Web、Cherry Studio 这类都支持自定义 Base URL。
官方 README 顶部写着一条前置约束:使用者需遵守 OpenAI 使用条款及所在地区法律法规,不得用于非法用途。按《生成式人工智能服务管理暂行办法》要求,对中国境内公众提供未经备案的生成式人工智能服务不在允许范围内。自建自用与对外售卖 API 服务,性质不同。
部署方式怎么选与最小可用步骤
官方给了四条部署路径。系统默认监听 3000 端口,初始账号 root、密码 123456,首次登录后必须改掉。
| | |
|---|
| docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api | |
| 在上面命令里加 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" | |
| 仓库自带编排文件,docker-compose up -d | |
| 下载 Releases 里的可执行文件,跑 ./one-api --port 3000 --log-dir ./logs | |
| | |
几个容易踩的点。挂载出来的宿主机目录要提前建好并有写权限,否则容器起不来;用 SQLite 时不挂 volume,容器一重建数据就没了;镜像拉不动可换成 ghcr.io/songquanpeng/one-api;并发量大务必设 SQL_DSN 走 MySQL。
多机部署还有四个条件:各节点的 SESSION_SECRET 设成同一个值;都连同一个数据库;从节点把 NODE_TYPE 设成 slave;再配 SYNC_FREQUENCY 定期同步配置,用远程数据库时建议同时启用 Redis。
在渠道页接入上游 API Key
系统起来后用 root 登进去,第一件事是去「渠道」页添加上游密钥。渠道类型有 51 种可选,覆盖 OpenAI、Azure、Anthropic、Gemini、DeepSeek、豆包、ChatGLM、文心一言、讯飞星火、通义千问、腾讯混元、Moonshot 等,另有两个兜底类型:OpenAICompatible 能接任何兼容 OpenAI 格式的服务。 新增渠道要填名称、分组、密钥、模型列表四项。密钥支持批量,一行一个。模型列表最容易漏,报「当前分组下对于模型 xxx 无可用渠道」十有八九出在这里。
- 豆包要先去火山引擎的模型推理页面创建推理接入点,用接入点名称当模型名,形如 ep-20240608051426-tkxvl。想让调用方写正常名字,可配合模型映射把 doubao-lite-4k 指向它,两个名字都要填进模型列表。
- Coze 的模型名就是 Bot ID,可加 bot- 前缀写成 bot-123456。
- 渠道测试只测对话类模型,优先用 gpt-3.5-turbo,不可用时才退回模型列表里的第一个。测试失败不等于渠道坏了。
- 分组倍率在系统设置里改。渠道填的分组名必须先在分组倍率里存在,两边对不上同样报无可用渠道。
创建令牌并替换 Base URL
上游接好后去「令牌」页点「添加新的令牌」,要填名称、模型范围、IP 限制、过期时间、额度。模型范围留空即不限制;IP 限制支持网段写法,多个用英文逗号隔开;过期时间格式是 yyyy-MM-dd HH:mm:ss,-1 表示永不过期。保存后回列表页点复制。
令牌本体是 48 位字符。客户端若不接受不带前缀的密钥,补上 sk- 也能识别,因为 One API 校验时会先剥掉 Bearer 与 sk- 两层前缀。
核心只有两步改动。
- 把 API Base 指向你的部署地址。以 OpenAI 官方库为例,写成 OPENAI_API_KEY="sk-你的令牌" 与 OPENAI_API_BASE="https://你的地址:3000/v1"。
- 把 API Key 换成刚复制的令牌。其余参数原样不动,模型名照填上游原名。
这里有个高频卡点:API Base 到底要不要带 /v1。官方 README 的说法是格式取决于客户端,因为它会做路径拼接。走 OpenAI 官方 SDK 就写到 /v1 为止;有的客户端只填到域名或端口,剩下的自己补。填错的表现是 404 或 Invalid URL,加一次去一次就能定位。
| | |
|---|
| | |
| | |
| | |
| | |
| | 要流式响应带 usage 需开 ENFORCE_INCLUDE_USAGE |
想锁定某个渠道,把渠道 ID 用连字符缀在令牌后面,写成 Authorization: Bearer 你的令牌-3。该能力只对管理员令牌开放,普通用户加后缀会收到 403。
失败重试默认 0 次,即不重试,需自己去系统设置里调高。重试策略写死在代码里:429 与 5xx 会换渠道再试,400 和 2xx 不重试;一旦指定了渠道 ID,就完全不走重试。
支持哪些调用端点与请求参数
One API 把 OpenAI 的接口路径整套搬了过来,但只实现了一部分。下表按源码路由逐个核对得出。
| | |
|---|
| | |
| | |
| | |
| | |
/v1/audio/transcriptions、/v1/audio/translations | | |
| | |
| | |
/v1/models、/v1/models/{model} | | |
| | |
/v1/assistants、/v1/threads 全系 | | |
/v1/files、/v1/fine_tuning/jobs 全系 | | |
/v1/images/edits、/v1/images/variations | | |
DELETE /v1/models/{model} | | |
未实现的端点返回的不是 404,而是 501,响应体是固定一句「API not implemented」,类型字段标成 one_api_error。依赖 Assistants、Threads、文件上传或微调的应用接到后面会直接失败。
请求体是否原样透传,取决于三个条件同时成立:渠道类型是 OpenAI、该模型没配模型映射、渠道没设强制系统提示词。任一条不满足,请求体就会被重新解析再序列化。官方功能列表里那句提醒说的就是这件事:模型映射如无必要不要设,设了之后请求体会被重构而非透传,一些尚未正式支持的字段会传不过去。
额度扣费与调用报错速查
One API 是预付费模式,先充值或用兑换码,额度换算默认基准是 50 万额度等于 1 美元。实际扣费按官方 FAQ 的公式算:
额度 = 分组倍率 × 模型倍率 ×(提示 token 数 + 补全 token 数 × 补全倍率)
补全倍率对 GPT-3.5 固定在 1.33,GPT-4 是 2,与官方一致。分组倍率与模型倍率都在系统设置的倍率设置里改,改完立即对新请求生效。
发请求前会先扣一笔预扣额度,公式是「预扣基数 500 + 提示 token 数 + max_tokens」再乘总倍率;账户余额大于预扣额度的 100 倍时免掉预扣。这解释了一个常见困惑:max_tokens 设得很大时,即使实际只输出几十个 token,也会按声明的上限预扣,余额不够就当场 403。过程中上游报错,预扣额度会退回。
| | |
|---|
| | |
| | |
| | |
| | |
| | 环境变量 GLOBAL_API_RATE_LIMIT |
| | 环境变量 GLOBAL_WEB_RATE_LIMIT |
| | |
| | |
两种额度分开计算:令牌额度只限制该令牌本身能用多少,账户余额才是大盘子,实际能取两者中的小值。令牌页面自己就写着这句话。
报错里会带一串 request id,格式是在原文后接 (request id: xxx),同一个值也出现在响应头 X-Oneapi-Request-Id 里。拿它去日志页搜,能定位到这次请求命中了哪个渠道。
| | |
|---|
| 未带 Authorization 头,或令牌不存在 | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
503 当前分组 xxx 下对于模型 xxx 无可用渠道 | | |
| | |
One API 调用常见问题
Q:One API 本身要收费吗?
A:软件不收费,成本来自服务器开销与付给上游的 token 费。协议要求页脚保留署名与指向项目的链接。
Q:不自己部署能直接用吗?
A:不能。它是自托管网关,必须先在服务器或本机跑起来,官方没有面向公众的托管服务。
Q:哪些客户端能接进来?
A:凡是支持自定义 API Base 的都能用。官方 README 给了 ChatGPT Next Web、ChatGPT Web、QChatGPT 三个配置示例。
Q:提示「当前分组下对于模型 xxx 无可用渠道」怎么排查?
A:三步走。先看渠道的模型列表里有没有这个模型名,再看渠道分组与用户分组能否对上,最后确认分组倍率里配了这个分组名。
Q:账户有余额,为什么还提示额度不足?
A:令牌额度与账户额度是两套账,真正的约束是账户余额。另外预扣费会先扣一笔,max_tokens 写得太大会把预扣撑高,余额不够就 403。
Q:能指定用哪个渠道吗?
A:可以,把渠道 ID 缀在令牌后面,写成 Bearer 你的令牌-3。只有管理员令牌支持这个写法,普通用户加后缀会收到 403。
Q:能调 Assistants API 和文件上传吗?
A:不能。assistants、threads、files、fine_tuning/jobs 几组路径在源码里全部指向未实现,统一返回 501。
Q:令牌和系统访问令牌是一回事吗?
A:不是。令牌页生成的是给业务请求用的,48 位字符;个人设置里生成的是系统访问令牌,用来调管理接口,不能拿去请求模型。
Q:这个项目还在更新吗?
A:主分支最后一次提交停在 2025 年 2 月,最新正式版 v0.6.10 的发布时间也是 2025 年 2 月。上手前先看仓库的提交记录与 issue 状态,社区也有衍生项目在活跃维护。
内置的模型倍率与版本会随上游厂商调整,配置前在系统设置里确认当期口径即可。想跟进 One API 的更新与入口变化,可以关注本站的 AI 工具栏目。