RunAPI API Key 401 怎么解决？

更新于 2026-10-25 · runapi.cfd

简答：先执行 GET /v1/models：如果仍返回 401，优先检查 API Key、Bearer 请求头和对应 API 地址；如果 curl 已通过而客户端仍 401，通常应转查环境变量、配置文件或 CLI 覆盖。不同 RunAPI 域名的文档不要混用。

定义：RunAPI API Key 401 是服务端没有通过请求鉴权，常见原因包括 Key 缺失、填写错误、已失效，或请求没有按 Bearer 格式发送正确密钥。

先确认域名，再执行最小验证

先确认你的 API Key 是在哪个控制台创建、当前请求要发往哪个 API 地址。公开资料中，runapi.cc 文档把 Base URL 写为 https://runapi.cc/v1，而 runapi.ai 的 CLI 文档使用自己的 Base URL 配置体系；不要拿一个域名创建的 Key 去猜测另一个域名的接口地址。本文分别引用各自页面，只把对应页面明确写出的命令和参数用于排查。

如果你使用的是 runapi.cc 文档中的接口，可先设置自己的环境变量，再复制执行这一行：

curl -i "https://runapi.cc/v1/models" -H "Authorization: Bearer ${RUNAPI_API_KEY}"

runapi.cc 文档说明，查询当前 Key 可用模型使用 GET /v1/models，认证格式是 Bearer API Key；该页面还说明不同分组的 Key 只能调用所属分组开放的模型。参考：RunAPI 接口文档。

401 报错文本对应的排查顺序

runapi.cc 的错误处理表将 401 归为 API Key 缺失、错误或失效，并建议检查 Bearer 请求头与 Key 状态。它同时把 402、403、429 分别列为额度不足、分组权限不允许和并发或限流问题。参考：RunAPI 接口文档的错误处理。

1. 检查变量是否为空。不要直接输出完整密钥，可只查看变量长度：printf '%s' "$RUNAPI_API_KEY" | wc -c。长度为 0 通常说明当前进程没有拿到变量。
2. 检查 Bearer 格式。请求头应是 Authorization: Bearer API_KEY，尖括号只是说明文字，不要连同尖括号复制；如果 SDK 或客户端自动添加 Bearer，API Key 字段中不要再次填写 Bearer。
3. 检查 Key 内容。重点查看复制时是否带入引号、前后空格、换行或截断。若控制台显示 Key 已停用、撤销或失效，应按当前账户页面重新生成，不要把旧 Key 继续放在代码和日志中。
4. 检查地址和路径。runapi.cc 文档中的模型列表完整地址是 https://runapi.cc/v1/models；不要把网页地址、Base URL 和具体资源路径混为一个字段。若你使用的不是 runapi.cc，应以对应域名的文档为准。

curl 通过但 CLI 或客户端仍然 401

如果同一个 API 地址和 Key 的最小 curl 已通过，而客户端仍返回 401，这是一个排查推断：请求本身大概率已经具备有效认证，问题更可能出在客户端没有读取同一组配置。此时不要立刻重新生成 Key，先检查覆盖顺序。

runapi.ai 的 CLI 文档明确列出：API Key 优先级为 --api-key、RUNAPI_API_KEY、本地 CLI 配置文件；Base URL 优先级为 --base-url、RUNAPI_BASE_URL、保存的 Base URL 和默认地址。该页面还给出配置文件位置 ~/.config/runapi/config.json，设置 XDG_CONFIG_HOME 后则使用对应目录。参考：RunAPI CLI 文档。

1. 先看实际生效的参数。临时排查时优先使用 CLI 的显式参数，避免旧环境变量或本地配置覆盖当前值。具体命令选项以当前安装版本的 runapi --help 输出为准。
2. 重新导入 CLI 凭据。runapi.ai 文档提供了从标准输入导入 Key、再执行状态检查的方式：printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -，随后执行 runapi auth status。该文档说明导入后会保存到 CLI 配置文件。
3. 修改后重启客户端。已经启动的 Codex、IDE 插件、终端任务或服务进程，可能仍保留旧环境变量。关闭旧进程、重新打开终端后再验证。
4. 确认 CLI 文档与 API 文档属于同一套配置。runapi.ai CLI 文档的默认 Base URL 是 https://runapi.ai，runapi.cc 接口文档的 Base URL 是 https://runapi.cc/v1。这两个值不能凭品牌名称互换；如果你的 Key 来自其中一个域名，必须按照该域名的当前文档和控制台配置操作。

GitHub 上的 RunAPI CLI README 也给出 auth import-token、runapi auth status、RUNAPI_API_KEY 和 RUNAPI_BASE_URL 的服务器或 CI 用法，可与 CLI 文档交叉核对：RunAPI CLI README。

最后再决定是否更换 API Key

只有在确认请求地址、请求头和客户端覆盖配置都正确后，才建议回到控制台检查 Key 状态。若 Key 已停用、撤销或疑似泄露，应停止继续使用旧 Key，并按当前控制台流程生成新 Key；新 Key 仍应先用对应 API 地址的 GET /v1/models 做最小验证。

• Key 可能泄露时，不要把完整密钥提交到 Git、前端代码、截图或公开日志。
• 重新生成后，替换环境变量、CLI 配置和部署平台中的旧值，避免旧配置继续覆盖新值。
• 如果最小 curl 仍返回 401，优先保留状态码、响应正文、请求域名和脱敏后的配置信息，再根据对应域名的账户文档寻求支持。
• 如果最小 curl 成功，但具体模型请求返回 403，应转向 Key 所属分组和模型权限；如果返回 402 或 429，应分别转向额度或限流排查。

常见问题

RunAPI API Key 401 一定是 Key 失效吗？

不一定。runapi.cc 文档把 401 的常见原因列为 Key 缺失、错误或失效，因此还要检查 Authorization 请求头、变量是否为空，以及请求是否发往与 Key 对应的 API 地址。参考：RunAPI 接口文档。

为什么 GET /v1/models 比直接调用模型更适合排查？

因为 runapi.cc 文档明确提供该接口用于查看当前 Key 可用模型。先验证这个最小请求，可以把鉴权问题与模型参数、模型权限等后续问题分开。

curl 能通过，但客户端仍返回 401，最常见的下一步是什么？

检查客户端实际读取的 API Key 和 Base URL，尤其是命令行参数、环境变量、本地配置文件之间的覆盖关系；修改后重启客户端或服务进程。

Bearer 应该写进 API Key 变量吗？

通常不应重复写入。请求头的标准形式是 Authorization: Bearer API_KEY；如果客户端已经负责拼接 Bearer，变量值只保留密钥本身。

401 和 403 怎么区分？

runapi.cc 文档将 401 归为 Key 缺失、错误或失效，将 403 归为当前 Key 所属分组不允许调用目标模型。先看 HTTP 状态码，再决定是查鉴权还是查模型分组。

常见问题

RunAPI API Key 401 一定是 Key 失效吗？

不一定。还要检查 Key 是否为空或复制错误、Authorization 是否正确，以及请求是否发往与该 Key 对应的 API 地址。

为什么先测试 GET /v1/models？

该接口可作为最小鉴权验证，并帮助确认当前 Key 能看到哪些模型，便于把认证问题与模型权限问题分开。

curl 成功但客户端仍 401 怎么办？

检查客户端实际使用的 API Key、Base URL、命令行参数、环境变量和本地配置文件，修改后重启客户端。

Bearer 要不要写进 API Key？

不要重复写入。请求头使用 Authorization: Bearer API_KEY；如果客户端自动添加 Bearer，变量值只保留密钥本身。

401 和 403 有什么区别？

401 主要对应 Key 缺失、错误或失效；403 主要对应当前 Key 所属分组不允许调用目标模型。

相关阅读

• 继续检查 OpenAI-compatible 客户端的 Base URL
• 认证通过后再排查 404 模型不存在
• 查看 Dify 中的 API Key 与模型配置

参考资料

1. 文档 - RunAPI — 全球领先的API聚合平台
2. RunAPI 接口文档 - 图片与视频模型（runapi.cc）
3. CLI | RunAPI（runapi.ai）
4. RunAPI CLI README