> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aitokenhub.vip/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥

> API 密钥是什么、怎么创建、填到哪里，以及怎么管理和保护它。

API 密钥是一串以 `tk_live_` 开头的字符串，是你调用 TokenHub 的凭证。把它和 TokenHub 的地址一起填进 Claude Code、Codex 或你自己的程序，请求就会经过 TokenHub，费用从你的余额里扣。

> [!TIP]
>
> 只是在自己电脑上用 Claude Code？用 [qlaude](https://docs.aitokenhub.vip/qlaude/getting-started.md) 在浏览器里登录更省事，不需要创建和保管密钥。API 密钥适合服务器、CI、脚本，以及 Codex 和你自己写的程序。

## 一把密钥包含什么

| 属性 | 作用 |
| - | - |
| 归属 | 创建时所在的个人或团队。这把密钥的所有调用都从它的余额里扣费 |
| 分组 | 决定能用哪些模型、走哪种接口（Claude Code 用的 Anthropic 接口，或 Codex 用的 OpenAI 接口），以及计费倍率 |
| 支出上限 | 选填。这把密钥累计花到这个金额后，就会停止工作 |

## 创建密钥

**1. 确认个人或团队**

密钥属于创建时所在的个人或团队。先在侧边栏顶部的 **个人与团队** 里选好，例如想用团队余额付费就切到对应团队。

**2. 打开密钥设置**

在左侧菜单进入 **账户 → 密钥设置**，点右上角的 **新增密钥**。

![密钥设置页面，右上角有「新增密钥」按钮](https://mintcdn.com/ai-token-hub/LSNqcyepOn4wFoWM/images/api-keys/list.png?fit=max\&auto=format\&n=LSNqcyepOn4wFoWM\&q=85\&s=a07d4258a212e2da317e7f8be40b803a)

**3. 填写名称、分组和支出上限**

![新增密钥对话框](https://mintcdn.com/ai-token-hub/LSNqcyepOn4wFoWM/images/api-keys/create.png?fit=max\&auto=format\&n=LSNqcyepOn4wFoWM\&q=85\&s=198be7bd97c5cb844fbb1c3a6c74158b)

* **名称**：必填，用来区分密钥用在哪里，例如 `my-laptop`、`ci-runner`。
* **分组**：必填。选好后，标签右侧会显示这个分组的计费倍率，例如 `1.00x`。用 Claude Code 就选面向 Claude 的分组，用 Codex 就选面向 Codex 的分组；拿不准可以问平台管理员。
* **支出上限（美元，选填）**：给 CI、脚本这类无人值守的用途设一个上限，防止意外花超。留空表示不限。

对话框底部会提示这把密钥从哪里扣费，例如「这把密钥的调用从你的个人余额扣费」。确认无误后点 **创建**。

**4. 复制并保存密钥**

![密钥创建成功，显示完整密钥和复制按钮](https://mintcdn.com/ai-token-hub/LSNqcyepOn4wFoWM/images/api-keys/created.png?fit=max\&auto=format\&n=LSNqcyepOn4wFoWM\&q=85\&s=e02db31c6019b57360e65613bd664050)

点 **复制**，把密钥保存到安全的地方，比如密码管理器，或直接写进要使用它的机器的环境变量。

> [!WARNING]
>
> 完整的密钥**只显示这一次**。TokenHub 不保存明文，点 **完成** 之后就再也看不到了。没来得及保存的话，只能吊销这把密钥，再新建一把。

## 使用密钥

在客户端里配置两样东西：**TokenHub 的地址**和**密钥本身**。

在 **密钥设置** 页点 **Endpoints**，可以看到并一键复制地址：

![Endpoints 面板，显示 OpenAI 兼容和 Anthropic 兼容两个 Base URL](https://mintcdn.com/ai-token-hub/LSNqcyepOn4wFoWM/images/api-keys/endpoints.png?fit=max\&auto=format\&n=LSNqcyepOn4wFoWM\&q=85\&s=0c6b1844c00fe319a195266022a32393)

两个地址的区别只在结尾的 `/v1`：

| 客户端 | 地址填 | 密钥填在 | 详细步骤 |
| - | - | - | - |
| Claude Code | `https://aitokenhub.vip` | 环境变量 `ANTHROPIC_AUTH_TOKEN` | [Claude Code](https://docs.aitokenhub.vip/integrations/claude-code.md) |
| Codex | `https://aitokenhub.vip/v1` | `config.toml` 里 `env_key` 指定的环境变量 | [Codex](https://docs.aitokenhub.vip/integrations/codex.md) |
| Anthropic SDK | `https://aitokenhub.vip` | `api_key` 参数 | [直接调用 API](https://docs.aitokenhub.vip/integrations/api.md) |
| OpenAI SDK | `https://aitokenhub.vip/v1` | `api_key` 参数 | [直接调用 API](https://docs.aitokenhub.vip/integrations/api.md) |

配置好之后，可以先用下面的命令确认密钥有效。它会列出这把密钥能用的模型，不收费：

```bash theme={null}
curl https://aitokenhub.vip/v1/models \
  -H "Authorization: Bearer <your-api-key>"
```

返回模型列表就说明密钥可用；返回 `401` 说明密钥填错了或已被吊销。

> [!NOTE]
>
> 密钥能不能用于某个客户端，取决于它绑定的分组。面向 Claude 的分组只能给 Claude Code 等 Anthropic 接口的客户端用，面向 Codex 的分组只能给 Codex 等 OpenAI 接口的客户端用。同时用两种客户端，就分别建两把密钥。

## 管理密钥

**密钥设置** 页列出当前个人或团队的所有密钥（见上方截图）：

| 列 | 含义 |
| - | - |
| 状态 | 见下表 |
| 分组 | 当前绑定的分组。倍率不是 `1.00x` 时会显示在名称后面 |
| 本月消费 | 本自然月（北京时间）的扣费合计，不能重置 |
| 累计用量 | 用来对照支出上限的金额。设了上限时显示进度条，没设显示「不限额」 |
| 最近使用 | 最后一次有请求的时间 |

| 状态 | 含义 | 怎么恢复 |
| - | - | - |
| 正常 | 可以使用 | — |
| 超预算 | 累计用量达到支出上限，请求会被拒绝（402） | 编辑密钥，调高上限或重置累计用量 |
| 已停用 | 被平台管理员停用，请求会被拒绝（403），列表里会显示停用原因 | 联系平台管理员 |

点密钥名称，可以打开它最近 30 天的用量看板：总消费、调用数、成功率、缓存命中率、总 token、平均首字延迟，以及每天的使用趋势。

### 编辑密钥

点密钥右侧的铅笔图标：

![编辑密钥对话框](https://mintcdn.com/ai-token-hub/LSNqcyepOn4wFoWM/images/api-keys/edit.png?fit=max\&auto=format\&n=LSNqcyepOn4wFoWM\&q=85\&s=0bbc6d30ea9dee7c0d11fa124143af02)

* **分组**：改绑后立即生效，客户端里的密钥不用换。
* **支出上限**：留空或填 0 表示不限。下方会显示当前累计用量。
* **重置累计用量**：把累计用量清零，支出上限从头计算。本月消费和用量记录不受影响。

### 吊销和删除

点密钥右侧的垃圾桶图标可以 **吊销** 这把密钥；勾选多把后点 **删除** 可以批量处理。使用这些密钥的请求会立即失败，操作不可撤销，已有的用量记录会保留。

## 安全建议

* **一个用途一把密钥**：笔记本、CI、服务器分开建，出问题时可以单独设上限、单独吊销。
* **不要暴露密钥**：不要写进网页前端代码、提交到代码仓库，或者发到聊天群里。
* **给无人值守的用途设上限**：CI 和脚本出 bug 时可能短时间内发出大量请求。
* **泄露后立即吊销**：先吊销旧密钥，再新建一把替换。
* **密钥不会自动过期**：不再使用的密钥请主动吊销。

## 在团队里

* 团队的所有者和管理员可以看到并管理全体成员的密钥，普通成员只能看到自己创建的。
* 团队给你设了[成员额度](https://docs.aitokenhub.vip/console/teams.md)时，你名下所有密钥和设备合计不能超过这个额度。
* 成员被移出团队后，该成员在这个团队创建的密钥会失效。

## 常见问题

> **创建时忘记复制密钥了**
>
> 完整密钥只在创建时显示一次，之后任何人都查不到。吊销这把密钥，再新建一把即可。

> **密钥从哪个余额扣费？**
>
> 从创建时所在的个人或团队扣费，之后不能更改。想换个团队付费，就在那个团队里新建一把密钥。

> **能限制一把密钥只用某些模型吗？**
>
> 可用模型由分组决定，不能按密钥单独设置。需要不同的模型范围，就给密钥换一个分组。

> **同一把密钥能在多台机器上同时用吗？**
>
> 可以。并发上限按个人或团队计算，所有密钥和设备共用。不过为了方便管理和排查，建议每台机器各用一把。

> **请求返回 401、402 或 403**
>
> * `401`：密钥填错、少复制了几位，或者已被吊销。
> * `402`：余额不足，或者密钥 / 成员额度用满了。
> * `403`：密钥被停用，或者客户端不被这个分组允许。
>
> 完整列表见 [错误码](https://docs.aitokenhub.vip/reference/errors.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.