# API 密钥与路由

> 来源： https://docs.xycai.us/zh/keys.html  
> XycAi 开发者文档 · Markdown 版，供 AI / LLM 阅读。全站索引：https://docs.xycai.us/llms.txt

一个 Key 就是一条**路由规则**：它决定请求可以到达哪些厂家、哪些模型，以及网关在多个定价分组之间如何自动选择。Key 在控制台「[API 密钥](https://www.xycai.us/keys)」页面创建，形如 `sk-xxxxxxxx`。

## 一、三种路由模式

创建 Key 时选择「路由方式」，三种模式覆盖绝大多数场景：

| 模式 | 可访问范围 | 适合 |
|---|---|---|
| **按厂家选择** 默认 | 所选厂家的全部模型（如 Anthropic = 全部 Claude），网关在该厂家的各分组内智能路由 | Claude Code / Codex 等单厂家客户端，按团队或项目分 Key |
| **按模型选择** | 只放行勾选的模型，可跨厂家；仍按最便宜可用分组路由 | 给下游系统或外包团队限定可用模型 |
| **全部模型与厂家** | 站内全部模型，无限制 | 自己使用、Cherry Studio / Chatbox 等多模型客户端 |

> **厂家与模型名的关系**
>
> 请求体里的 `model` 决定调用什么模型；Key 的路由模式决定这个模型**允不允许**以及**走哪个分组**。用按厂家（Anthropic）的 Key 去调 `gpt-5.6-terra` 会返回 `403`，换成「全部模型与厂家」或在「按模型」里勾上即可。

## 二、智能路由怎么选分组

同一个模型往往同时存在于多个定价分组（例如 `claude-opus-5-5` 同时在 Claude 企业版与编程套餐分组）。网关按下面的顺序为每次请求挑分组：

1. **按真实扣费从低到高排序** 候选 = 你账户可用的分组中含该模型的分组，按折扣后的实际价格升序；同价按分组默认顺序。
2. **最便宜的分组优先** 首选最便宜的一档；该分组没有该模型的可用渠道时，自动升到下一档。
3. **故障自动切换** 上游返回错误时在同分组内换渠道重试，仍失败则升档重试；全部失败才把错误返回给你。
4. **兜底分组** 仅存在于特殊分组（无限制版 / 未审查版）的模型，会在常规分组都没有时才命中。

因此通常**不需要**手动选分组；用量明细中的每一条记录都会标明实际命中的分组与单价。

## 三、分组体系

分组是定价与上游资源池的单位。模型列表里的分组徽标含义如下：

| 分组 | 含义 | 典型 |
|---|---|---|
| 企业版 | 官方满血、官方母号、无客户端限制，全模型长上下文、图片、搜索；适合大项目主要生产力 | Claude 企业版、GPT 企业版、Gemini 企业版、GLM / Kimi / DeepSeek / Qwen 企业版 |
| 经济版 | 特价号池，价格更低；GPT 经济版限制 Codex 客户端且不能生图，部分不保障缓存命中率 | Claude 经济版、GPT 经济版、Gemini 经济版、GLM 经济版 |
| 学习版 | 引流特价分组，不参与智能路由自动兜底，需单独选用 | Claude 学习版 |
| 工作流 | 官方原价，提供厂家完整型号目录（含历史型号）；适合非编程工具链与批处理 | GPT / Claude / GLM / Gemini / Cohere / Mistral 工作流 |
| 套餐 | 编程套餐订阅分组：按套餐并发与额度计费，用尽后回落钱包 | Claude Code / Codex 套餐 |
| 福利 / 免费 | 免费或福利分组，不保障可用率；仍需账户为正余额 | DeepSeek 福利免费版、TypeSafe 福利版 |
| 未审查版 | 第三方未审查号池的图片 / 视频模型，按张或按秒计费 | Seedream / Seedance / Qwen Image / Wan / MiniMax H3 / FLUX / LTX |
| 无限制版 | 未删减（Uncensored）与消融（Abliterated）模型 | GLM-5.3 / DeepSeek V4 Pro 无限制、Roleplay |

每个分组的折扣、按模型单价与分档价见控制台[模型广场](https://www.xycai.us/pricing)，价格以那里为准。

## 四、额度模式

每个 Key 可独立设置消费上限，三选一：

| 模式 | 说明 |
|---|---|
| **不限额** | 只受账户余额限制（默认） |
| **固定总额度** | 该 Key 累计消费到上限后拒绝请求（`429`），可随时在控制台调高 |
| **周期额度** | 按日 / 周 / 月自动重置；周期锚定你保存设置的那一刻，每个整周期清零一次 |

此外可以设置 **过期时间**与 **IP 白名单**；Key 被删除后立即失效。

## 五、并发与速率限制

- 并发按**用户等级**限制：未定级（T0）**30** 路并发；T1 及以上 **300** 路。超限返回 `429`，并附带说明文案。
- 编程套餐分组按套餐自带的并发池计数，不与上面叠加。
- 生图接口另有独立的并发闸，避免突发大批量生图影响其他请求。
- 有真实的高并发需求（批处理、评测）请联系客服说明用途，可按账户放开上限。无意义压测视为攻击，可能封号。

## 六、用户等级与折扣

账户按累计消费自动评定等级（T0 → T1 → T2 → V1 → V2），等级越高在各分组的折扣越低；等级与折扣矩阵在模型广场可见。等级作用于账户下全部 Key，无需重建 Key。

## 七、建议做法

- **按用途拆 Key**：Claude Code 一把（按厂家 Anthropic）、Codex 一把（按厂家 OpenAI）、聊天客户端一把（全部模型），互不影响、各自看用量。
- **给下游系统用「按模型」**并设固定或周期额度，避免被误用。
- Key 只放在服务端 / 环境变量；前端或移动端调用请经过你自己的后端转发。
- 调用 `GET /v1/models` 可以实时看到当前 Key 能访问的模型清单，适合排查 `403`。