# KeepRouter API Key 配置：从免费模型走到一次受控付费请求

> 先用公开的 free 模型检查认证与基础聊天请求。切换付费模型时，需要准确目录 ID、允许该模型的 Key 和足够预付余额。先核对一次请求，再扩大调用。

_发布 2026-09-23 · 更新 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 6 分钟阅读_

![应用、AI Gateway 与模型供应商之间的分层责任图](https://keeprouter.com/editorial/blog/ai-gateway-guide.png)

_认证、模型范围、账户余额与有用输出是不同检查项。_

第一笔 KeepRouter 请求应回答一个很小的问题：这个应用能否正确认证，并从预期端点收到响应？先选择公开的 [free 模型](/models/free)，创建仅允许它的 Key。基础路径运行正常后，再用独立范围和可核对请求评估一个付费模型。

KeepRouter 的付费用量从预付美元余额扣除。free 是具体目录条目，它的存在不代表整个目录都免费。类似地，免费文本请求成功，也不能证明某个付费模型的工具调用、图片处理、上下文行为或回答质量。[快速开始](/docs/quickstart)与实时目录是本文操作步骤的当前参考。

## 为明确用途创建 Key

通过站点的登录入口进入账户控制台，为测试应用创建 Key。使用容易识别的名称，便于以后区分请求。第一轮将模型 allowlist 限制为 `free`；需要时，再按控制台提供的选项设置过期时间和消费限制。

把显示的凭证保存到运行环境的密钥存储或本地环境变量。不要放进浏览器打包文件、公开仓库或客服截图。Key 用来让服务识别应用，模型 allowlist 决定它可以请求哪些目录模型；账户余额与 Key 权限是两个独立条件。

| 控制项 | 回答的问题 | 不能据此推断 |
|---|---|---|
| 凭证 | 调用方是否被识别 | 是否允许全部模型 |
| 模型范围 | 该模型是否获准调用 | 账户是否有付费余额 |
| 消费控制 | Key 是否仍在配置预算内 | 端点是否与模型兼容 |
| 账户余额 | 是否能够支付付费用量 | 输出是否满足应用要求 |

新客户端排错时，尽量不要直接使用范围宽泛的生产 Key。独立测试 Key 的流量更容易识别，实验结束后也可以单独撤销，而不影响其他应用。

## 运行一个最小免费请求

在当前进程环境中设置 `KEEPROUTER_KEY` 后，下面的 Python 代码会发送一笔基础聊天请求。它读取变量的值，不会把变量名误当成密钥。示例供你自行运行，不代表本文已经替任何账户创建凭证或执行请求。

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://keeprouter.com/v1",
    api_key=os.environ["KEEPROUTER_KEY"],
    timeout=30.0,
    max_retries=0,
)
reply = client.chat.completions.create(
    model="free",
    messages=[{"role": "user", "content": "Reply with a short greeting."}],
    max_tokens=64,
)
print(reply.id, reply.model)
print(reply.choices[0].message.content)
print(reply.usage.model_dump() if reply.usage else "usage missing")
```

使用当前可用的 OpenAI Python SDK，并在项目锁文件中记录版本。如果应用运行在容器或部署平台里，在另一个终端设置变量并不等于配置了该进程。可以确认运行环境是否读到变量，但不要打印值。

SDK 的 Base URL 为 `https://keeprouter.com/v1`，聊天操作路径由 SDK 追加。如果把完整 `/chat/completions` 当作 base，可能拼出错误地址。Anthropic 客户端的请求结构不同，需要该接口时应阅读 [Anthropic 兼容 API 指南](/zh/features/anthropic-compatible-api)。

## 按错误所在层逐项排查

| 现象 | 优先检查 |
|---|---|
| 401 | 当前进程有 Key、复制无误、未被撤销 |
| 模型被拒绝 | 请求 ID 是否在 Key 的 allowlist 中 |
| 模型不存在 | 当前目录有该 ID，没有照抄其他服务命名空间 |
| 404 | 主机和基础路径是否适合该客户端 |
| 余额或预算不足 | 账户余额与此 Key 的剩余额度 |
| 操作不支持 | 模型是否公布了所调用端点 |

保留请求标识和状态，便于后续诊断。认证失败不应该靠充值解决；账户有余额，也不能修复错误 Base URL。一次只改一个关键设置，并先阅读[错误参考](/docs/errors)。联系支持时，发送安全的请求元数据和已去除凭证的载荷，不要发送 API Key。

## 有意识地准备一次付费请求

从[模型目录](/models)中选一个候选，确认它的计费单位和端点。[Claude Sonnet 4.6](/models/claude-sonnet-4-6)这样的聊天模型，与图片、语音、视频线路是不同选择。使用 [API 费用计算器](/tools/api-cost-calculator)时，应填写该操作相应的 token 或其他单位假设。

在控制台新建 paid-test Key，并将所选准确模型加入它的 allowlist。保留原来的 free-only Key，可以让两种测试各自范围清晰。通过控制台当前提供的支付流程增加预付余额，并在余额页面确认入账。查看结账显示的总额、适用费用和税额；模型 token 单价与支付结账金额不是同一概念。浏览器跳转完成，也不能单独证明信用余额已经到达账户。

将应用运行环境中的 `KEEPROUTER_KEY` 更新为刚创建的 paid-test Key，然后重启进程或重新创建 SDK client，确保它读取新值。已经用 free-only Key 创建的客户端仍持有旧凭证；充值或修改模型 ID 不会替换这个凭证。

限制测试规模，采用所选线路支持的输出上限，并发送有明确预期的合成任务。仅对兼容聊天模型复用前面的脚本：把 `free` 换成已核实 ID，并根据线路调整字段。非聊天模型需要它自己的操作和载荷，不能只换一个名字继续请求。

## 将响应与用量记录对上

付费调用后，在控制台核对请求模型、时间、状态、输入、输出、缓存信息及扣费；应用侧保留请求标识。如果客户端超时，应先检查请求记录，再决定是否重复。超时不等于上游从未执行工作，也不意味着该次调用一定免费。

应区分四个里程碑：账户已经建立、Key 能认证、请求已经完成、结果实际有用。即使前三项通过，产品仍可能需要调整提示词或重新评估模型。应关注第一次有用的付费任务，而不是把创建 Key 当成完成采用。

## 弄清免费调用已经证明了什么

免费模型调用成功，证明该 Key 与型号的基本客户端路径可用，不证明付费型号已有足够余额、在 Key 范围内或支持全部字段。首次付费请求前，打开目标模型页，检查单位价格和输出限制，再核对一次用量记录。[KeepRouter 快速开始](https://keeprouter.com/docs/quickstart)是设置参考。第一项付费任务尽量简单，方便理解和纠正错误。

## 将验证过的配置移入应用

将 Base URL 和准确模型 ID 保存为配置，在运行时注入密钥；条件允许时，为不同应用环境使用独立 Key。部署后发出一个无害且有边界的请求，并核对用量记录。应用 Key 检查完成后，再撤销一次性测试 Key。

把 [SDK 配置指南](/use-cases/openai-sdk)加入应用操作手册。工作负载明显变化前，应重新查看模型端点和客户价格。增加并发、接入工具或发送图片，都会形成新的测试案例；最初那条免费问候不能替代这些检查。

## 常见问题

### 充值前可以测试吗？

可以使用公开 free 模型和仅允许 free 的 Key，具体仍受当前可用性与限制约束。

### 免费请求成功后，付费请求为什么还会失败？

应分别检查付费模型 ID、Key 范围、余额、Key 限额和端点。

### 创建 Key 就算成功激活了吗？

不是。还应验证请求完成与应用结果有用，付费采用还需理解扣费。

### 排错时应该提供什么？

提供请求时间、标识、模型、状态与去除凭证后的载荷信息，不要提供 API Key。

## 参考的一手资料

_本文最近复核 2026-09-29_

1. [KeepRouter quickstart](https://keeprouter.com/docs/quickstart)
2. [KeepRouter free model](https://keeprouter.com/models/free)
3. [KeepRouter error reference](https://keeprouter.com/docs/errors)
4. [OpenAI Python SDK](https://github.com/openai/openai-python)

## 继续阅读

- [free](https://keeprouter.com/models/free.md)
- [quickstart](https://keeprouter.com/docs/quickstart.md)
- [errors](https://keeprouter.com/docs/errors.md)
- [api cost calculator](https://keeprouter.com/tools/api-cost-calculator)
- [DeepSeek API 价格：缓存命中后，怎样不重复计算输入费用](https://keeprouter.com/zh/blog/deepseek-api-pricing-cache-estimation.md)
- [从 OpenRouter 迁移到 KeepRouter：核对 URL、模型 ID 与路由字段](https://keeprouter.com/zh/blog/openrouter-to-keeprouter-migration.md)

## 用一条小请求试用接入配置

按步骤设置，把密钥保留在服务端，并检查返回的答案与用量。

[打开接入指南](https://keeprouter.com/docs/quickstart)

[创建 Key，测试免费模型](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

免费测试使用 free 模型；其他付费型号需要足够预付额度。

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)