API 密钥
用 API 密钥调用 Trinity HTTP API。密钥属于当前工作区；换区后请用该区下的 Key。完整明文只在创建时展示一次（前缀一般为 xh-...）。
| 我想… | 去这里 |
|---|---|
| 打开控制台 | 控制台 · API 密钥 ↗ |
| 创建 / 批量创建 | 创建密钥 |
| 限制某把 Key 能调哪些模型 | 模型访问（Key 层） |
| 给成员绑 Key | 成员管理 |
| 泄露后处理 | 轮换、停用与删除 |
| 调通第一笔请求 | 快速入门 |
先确认工作区
在要使用的工作区里创建密钥。顶级工作区也可建 Key，但不能邀成员；团队场景请在子工作区创建并分配。
打开控制台
路径：/account/workspace/{工作区标识}/keys
侧栏：API 密钥
入口：控制台 ↗（未登录会跳转官网登录）。
| 角色 | 能做什么 |
|---|---|
| owner / admin | 创建、编辑、停用/启用、删除、配模型访问、导出 CSV；子区可批量给成员绑 Key |
| member | 查看分配给自己的 Key；通常只能改名称等有限字段，不能自建 |
在顶级工作区且你是 owner 时，列表可能汇总账号下各工作区的密钥（点工作区名可切换）；在顶级创建的 Key 仍归属顶级。
创建密钥
- 切到目标工作区，打开 API 密钥。
- 点击 创建。
- 填写并确认：
| 字段 | 说明 |
|---|---|
| 名称 | 必填，便于识别（如 prod-backend） |
| 额度上限（可选） | 美元整数；留空表示不限。可配合「重置额度周期」 |
| 重置额度周期 | 不适用 / 按小时·天·月等；或「每月 1 日」 |
| 过期时间 | 永不过期，或 1 小时～360 天 |
| 模型访问（可选） | 默认沿用工作区；可改为指定允许列表 |
- 提交后弹出完整密钥 → 立即复制保存（关闭后通常只能看到掩码；未开「安全保障」时或可用「复制 KEY」取回明文，见下文）。
- 写入环境变量或密钥管理系统，例如：
export TRINITY_API_KEY="xh-..."
export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"批量创建
owner / admin 可点 批量创建（单次最多 50 把）：共用名称前缀时，会生成 名称-1、名称-2…；同样只展示一次，可「复制全部」。
模型访问（Key 层）
对应权限三层里的 L3，不能宽于本工作区（L2）与账号（L1）。概念见 模型权限。
| 控制台文案 | 含义 |
|---|---|
| 全量模型支持 | 不额外限制，沿用工作区可用范围 |
| 指定允许列表 | 仅勾选的系列 / 模型可 Call |
创建时可选；创建后也可在行操作里打开 模型访问 再改。
用该 Key 调 GET /v1/models 时，通常只返回它能调用的模型。排查 403 model_not_allowed 见 Key 与模型权限。
列表与筛选
常见列：名称、掩码密钥、额度上限、重置周期、过期、归属人、用量、创建时间等。
可按名称、密钥尾缀（末 4 位）、使用中 / 已过期筛选；支持高级筛选（如归属人、未分配）与 导出 CSV。
轮换、停用与删除
| 操作 | 说明 |
|---|---|
| 轮换 | 新建 Key → 应用切到新 Key → 确认流量正常 → 删除或停用旧 Key |
| 停用 / 启用 | 临时切断调用，不必立刻删除 |
| 删除 | 不可恢复；之后携带该 Key 的请求会失败（多为 401） |
密钥泄露
先停用或删除，再在控制台核对近期 用量。不要只改名称。
分配给成员
在子工作区，owner / admin 可在 成员管理 为成员分配 / 解绑密钥，或使用密钥页的批量分配入口（若当前版本提供）。
member 若列表为空，需联系管理员分配——不能在顶级工作区完成组队分配。
安全保障（可选）
工作区可开启 安全保障：
- 开启后清除本区 Key 的明文存储；历史 Key 往往无法再「复制 KEY」取回。
- 开启前建议先 导出 CSV 备份；确认开启时可能自动下载备份。
- 关闭后，新建 Key 可再存明文并可复制；已清除明文的旧 Key 仍无法恢复。
按合规需要开启；个人试用可保持关闭以便复制调试。
推荐做法
| 场景 | 建议 |
|---|---|
| 本地调试 | 单独 Key，短过期或低额度上限 |
| 生产服务 | 独立 Key + 模型允许列表 + 合理额度 / 过期 |
| 多成员 | 子工作区一人一把（或按服务）Key，避免共用 |
| 外包结束 | 删除或停用其 Key，必要时移除成员 |
常见问题
创建后找不到完整密钥？
明文通常只展示一次。未开安全保障时，部分环境仍可用「复制 KEY」；已开启则需新建一把并更新调用方。
换工作区后旧 Key 还能用吗？
旧 Key 仍属于原工作区，请求会记在原区。应使用当前工作区下创建的 Key。
目录里看得到模型，Key 调不通？
多半是该 Key 的允许列表未包含该模型。编辑 Key 的 模型访问，或先放宽工作区 防护规则。
member 为什么不能创建 Key？
需 owner / admin 创建并分配。