接入教程

HiveGPT 提供和 OpenAI 一致的接口。几乎所有支持「自定义 OpenAI 接口」的工具和 SDK，填上 Base URL 和 API Key 就能用。

先准备好三样东西

准备	在哪里	说明
账号	注册 HiveGPT	邮箱注册即可
余额或订阅	充值 / 订阅	两种方式的区别见订阅还是按量
API Key	API 密钥	创建时选的分组决定能用哪些模型、怎么计费

分组怎么选

买了订阅：选哪个都行。同一个 Key 在对话和 Codex 请求里会先用订阅额度，额度用完或到期后自动改用余额，不用为订阅和按量各建一个 Key。
按量付费：选「GPT-按量」，调用从余额里扣。
选错分组是「模型不可用」最常见的原因。一个账号可以建多个 Key，分别用不同分组。

通用参数

不管用什么工具，需要填的都是这几项：

参数	填什么
Base URL / API 地址	`https://hivegpt.cn/v1`
API Key	你在「API 密钥」页创建的 `sk-` 开头的 Key
接口类型	OpenAI 兼容（Chat Completions；Codex 用 Responses）
模型	你的分组里可用的模型，例如 `gpt-5.5`，查法见下文

有的工具会自己补 /v1

如果工具提示 404 或「路径不存在」，把 Base URL 换成 https://hivegpt.cn 再试（去掉末尾的 /v1）；反过来也一样。各工具的具体填法见 Base URL 末尾要不要加 /v1。

选一个教程

你想用在	看这篇	大约用时
Codex（CLI、IDE 扩展、桌面端）	Codex 接入 HiveGPT	5 分钟
OpenCode、CodeBuddy、Cherry Studio、Chatbox 等工具	在常用工具里配置	3 分钟
自己写代码（Python、Node.js、curl）	用 SDK 调用	5 分钟
Cherry Studio 桌面客户端	Cherry Studio 配置教程	3 分钟
沉浸式翻译（网页、PDF 翻译）	沉浸式翻译接入 GPT API	3 分钟

最省事的办法：在「API 密钥」页找到你的 Key，点 「使用密钥」。弹窗会按你的分组和系统，直接生成 Codex、OpenCode 等客户端的配置，复制粘贴即可。

查看可用模型

不同分组能用的模型不一样，以接口返回为准：

bash

curl https://hivegpt.cn/v1/models \
  -H "Authorization: Bearer $HIVEGPT_API_KEY"

返回的 data[].id 就是可以填进工具里的模型名。

验证 Key 能用

bash

curl https://hivegpt.cn/v1/chat/completions \
  -H "Authorization: Bearer $HIVEGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'

能看到回答，说明 Key、余额（或订阅）和网络都没问题；控制台首页的「三步开始使用」也会自动打勾。之后在任何工具里出问题，基本就是那个工具的配置写错了。

常见报错

现象	原因	处理
提示 Key 无效、未授权（401）	Key 复制不全、已删除或已停用	到「API 密钥」页确认状态，重新复制完整的 Key
提示某个模型不支持或不存在	这个模型不在你 Key 的分组里	用上面的 `/v1/models` 查可用模型，或换一个分组的 Key
提示余额不足、额度已用完	余额为 0，或订阅的每日 / 每周 / 每月额度用完	充值，或等额度恢复；充值后同一个 Key 会自动改用余额继续
提示限流、请稍后再试（429）	请求太快，或上游临时限流	过 1–2 分钟再试；这类失败不扣费
上游暂时不可用（502 / 503）	模型服务临时故障	稍后重试；这类失败不扣费
一直转圈、回复很慢	上游繁忙，或者上下文太长	换一个较快的模型，或开新会话减少上下文

每次请求的模型、用量和费用都能在使用记录里查到。还有问题，可以问首页右下角的智能客服。

保护好你的 Key

Key 等同于余额。不要发到群里、截图里或提交到 Git 仓库。如果泄露了，立刻在「API 密钥」页删除，再建一个新的。

接入教程 ​

先准备好三样东西 ​

通用参数 ​

选一个教程 ​

查看可用模型 ​

验证 Key 能用 ​

常见报错 ​