HEAVEN API / GET STARTED
从兑换开始,
接通你的第一条请求。
先在后台完成兑换和密钥创建,再配置工具。每一步,都告诉你去哪里、怎么做、做到什么样才算成功。
准备好你的账户
登录 Heaven 控制台
打开登录页,使用你的 Heaven 账户登录。新用户可通过页面提供的注册入口创建账户。网站登录密码和 API 密钥是两种不同的凭证。
打开登录页面 ↗成功标志:进入控制台,菜单中可以打开「兑换码」和「API 密钥」。
让额度 / 权限到账
先兑换,再确认到账内容
- 进入控制台菜单「兑换码」,或点击下面的直达入口。
- 粘贴收到的兑换码,保持大小写并去掉首尾空格,点击「兑换」。每个兑换码只能使用一次。
- 查看成功结果:余额码增加余额,并发码增加并发请求数,订阅码开通对应分组与有效期。兑换订阅不一定增加余额。
在表单下方核对兑换结果与最近活动。
成功标志:出现兑换记录。订阅类请到「我的订阅」核对分组和有效期;若显示未刷新,先刷新页面核对,不要反复提交。
生成工具真正要用的密钥
创建密钥,选对厂商与分组
- 进入「API 密钥」→「创建密钥」。名称可填 My-Codex,方便以后识别。
- 本站 Claude Code 和 Codex 都可使用 OpenAI 兼容分组。创建密钥时选择「OpenAI」,再选择已开通对应工具权限的分组;Claude Code 需确认该分组已支持 Claude Code 兼容接入。Gemini 选择其对应分组,以账户实际权限为准。
- 检查额度上限和有效期;第一次接入可按需保留高级限制的默认值。关闭「自定义密钥」,让系统自动生成。
- 创建后,在密钥列表复制完整密钥。工具中填写这个密钥,不是兑换码,也不是登录密码。不同工具建议单独创建密钥。
实际选项以你账户中显示的权限为准。
先检查订阅是否生效、厂商是否选对。密钥的额度上限是使用限制,不是给账户充值。应有的分组没有出现时,请联系支持核对权限。
只看你要用的那一种
把 Heaven 接进你的工具
选择工具和系统,只看对应步骤。请在本机替换 YOUR_API_KEY 和 YOUR_GROUP_MODEL_ID。示例不包含真实密钥,本页也不会发起模型请求。
使用 Cursor、Cline 或其他客户端?
其他支持自定义服务商的客户端,选择对应协议,填写下方地址,在本机粘贴密钥与分组支持的精确模型 ID。不同版本的自定义地址支持可能不同,请结合客户端官方文档。
| 协议 | Base URL | 实际请求路径 |
|---|---|---|
| OpenAI Responses | https://ai.heaven.help |
/responses |
| OpenAI Chat Completions | https://ai.heaven.help/v1 |
/v1/chat/completions |
| Claude Code · Heaven 网关兼容 | https://ai.heaven.help |
/v1/messages |
| Gemini REST | https://ai.heaven.help |
/v1beta/models/… |
Base URL 不是完整请求地址。不要把 /responses、/messages 填进客户端的基础地址,也不要重复 /v1。有些客户端会自动加 /v1,请以其日志中的最终请求地址核对。
最后,把连接核对一遍
收到回答,也查得到记录
- 在 CC Switch 点击「获取模型列表」,手动配置则使用对应教程的本机查询命令。确认精确 ID 在当前分组可用;列出模型后仍需验证生成请求。
- 在配置好的工具中发送一句简短提问。自己的应用可替换模型 ID 后运行示例请求。生成请求会消耗额度;模型查询是单独的检查步骤。
- 进入「使用记录」,核对本次请求的时间、模型、状态和 Token 用量。遇到问题保留请求 ID,便于定位。
接入完成:工具正常收到回答,并且后台出现对应请求记录。现在,就可以开始你的工作了。
问题有迹可循
按报错,找到下一步
401 · 密钥验证失败
重新复制完整 API 密钥,检查空格、密钥禁用或过期,以及认证头是否正确。兑换码和网站密码都不能用于 API 认证。
403 / model_not_found · 分组或模型不匹配
核对密钥厂商、分组、订阅有效期与精确模型 ID。其他平台或旧教程里的名称不一定可用。有的客户端会显示 400 或 404,也要查看报错正文。
404 / 返回网页 · 地址填写错误
检查协议和最终请求地址,排除重复 /v1;不要把 /home、/login、/tutorial 当作 API 地址。若已通过认证但正文提示模型不存在,请转查模型与分组。
429 / 额度不足 · 限制或权限问题
结合报错区分余额、订阅用量、密钥额度、并发与频率限制。等待正在进行的请求结束或对应额度周期重置,避免连续重试。兑换并发数不会增加余额。
超时 / 5xx · 请求卡住或上游异常
先看「渠道状态」和「使用记录」。客户端超时不代表上游一定已取消,请先查记录再决定是否重发。联系支持时附上时间、工具版本、报错和请求 ID。
改了配置,工具却仍然使用旧设置?
环境变量示例仅对当前终端生效,请在同一终端启动工具。要永久保存,请按工具文档设置并重新打开终端或应用。已有配置先备份、再合并,不要整份覆盖;同时检查冲突环境变量和其他已启用的配置。
HEAVEN CARE
卡住的那一步,
我们陪你一起接通。
请提供工具版本、系统、报错时间、脱敏报错与请求 ID。请勿发送完整密钥、兑换码或密码。