API 密钥管理

平台用 API Key 鉴权。所有模型调用都带同一把 Key：

curl https://api.token.heimatianqi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-heima-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}]}'

创建与配置

控制台 →「API 密钥」→「创建 API 密钥」，可配置：

配置	说明
名称	仅用于你自己识别用途（例如 生产-后端服务）
额度	该 Key 的独立额度上限；可设为无限
分组	决定计费倍率与可用模型范围，默认 default
模型限制	只允许该 Key 调用白名单内的模型（留空=不限制）
IP 限制	只允许白名单 IP/IP 段调用（留空=不限制）

模型限制与 IP 限制是最小权限的关键：给每个服务单独发 Key，并把模型限制收紧到实际用到的型号。

一键导入客户端

每把 Key 的操作菜单里有**「CC Switch」与「聊天 / Chat」子菜单**，可把 Key 与接入地址 一键塞进常用客户端（Cherry Studio、AionUI、CC Switch、DeepChat、Lobe Chat、AI as Workspace、 AMA 问天、OpenCat、流畅阅读等）。客户端清单来自平台配置（/api/status 的 chats）。

验证这把 Key 能调用哪些模型

curl -s "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/models" \
  -H "Authorization: Bearer $HEIMA_API_KEY" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); assert d.get('data'), 'Empty model list'; print('models available:', len(d['data']))"

输出里的数量就是这把 Key 当前可用的模型数（受模型白名单与分组影响）。

安全建议

• Key 只放在服务端环境变量或密钥管理系统里，不要写进前端代码或公开仓库。
• 怀疑泄露时先禁用再新建（禁用立即生效，不需要等缓存）。
• 不同服务用不同 Key，出问题时可以只禁用受影响的那一把。

常见问题

• 401 Invalid token：Key 拼写错误、已被删除或已禁用。
• 403 no access to model：该 Key 的模型白名单里没有这个型号（或该型号未对外开放）。
• Key 不见了：密钥只完整显示一次，之后只显示掩码；丢失请重新创建。