API Key 问题

API Key 是调用零派智能API 接口的身份凭据。以下是在使用 API Key 时常见的问题及解决方案。

Key 格式不正确

现象

请求返回 401 Unauthorized，提示 API Key 格式无效或缺失。

原因

Key 中包含多余的空格、换行符或不可见字符
复制 Key 时遗漏了前缀部分（如 sk-）
代码中对 Key 做了错误的字符串拼接或截断

解决方案

检查 Key 是否以正确的格式开头（通常以 sk- 开头）
确保 Key 前后没有多余的空格或换行符
```
api_key = api_key.strip()
```
避免将 Key 硬编码在代码中，建议使用环境变量
Terminal window
```
export API_KEY="sk-your-api-key-here"
```

在请求头中正确传递 Key

curl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Key 已过期或被删除

现象

之前正常工作的 Key 突然返回 401 Unauthorized。

原因

Key 已超过有效期
Key 在管理后台被手动删除或禁用
Key 被系统自动过期

解决方案

登录管理后台，进入 API Key 管理 页面
查看对应 Key 的状态，确认是否为「已过期」或「已禁用」
如果已过期或被删除，创建一个新的 Key
将新 Key 更新到你的代码或工具配置中

Key 额度用尽

现象

请求返回 429 Rate Limit 或提示余额不足。

原因

Key 绑定的额度已用完
Key 设置了使用上限且已达上限
账户余额不足

解决方案

在管理后台查看该 Key 的额度使用情况
检查账户余额是否充足
如果额度用尽：
- 充值账户余额
- 调整 Key 的额度上限
- 联系管理员追加额度

Key 无权限访问某模型

现象

调用特定模型时返回 403 Forbidden，但其他模型正常。

原因

Key 的模型权限设置中没有包含目标模型
Key 被限制了可用的模型范围
目标模型需要更高的权限等级

解决方案

在管理后台查看该 Key 的模型权限设置
确认目标模型是否在允许的模型列表中
如果不在列表中：
- 修改 Key 的模型权限，添加目标模型
- 使用一个具有更高权限的 Key
- 联系管理员调整权限

如何检查 Key 有效性

使用以下方法快速验证 API Key 是否有效：

方法一：通过 Models 接口验证

curl "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

返回 200 及模型列表 → Key 有效
返回 401 → Key 无效或已过期

方法二：发送一个简单的 Chat 请求

curl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 5
  }'

返回 200 及正常响应 → Key 有效且可用
返回 401 → Key 无效
返回 403 → Key 有效但无权限
返回 429 → Key 有效但额度已用尽

方法三：通过管理后台查看

登录管理后台
进入 API Key 管理 页面
查看对应 Key 的状态、额度和权限信息