本文档说明如何通过 API 密钥对请求进行认证。认证是所有程序化调用的前提。
认证机制
Moxus AI通过 API 密钥（Bearer Token）识别请求来源。每次请求须在 HTTP 头中携带密钥，平台据此验证身份、权限与余额。缺少或错误的密钥将导致请求被拒绝（返回 401）。
OpenAI 兼容请求使用 Authorization: Bearer sk-你的密钥。Anthropic 原生接口也可使用 x-api-key: sk-你的密钥。
基础信息
| 项目 | 值 | 来源 |
|---|
| Base URL | https://moxus.ai/v1（OpenAI 格式） | 平台访问域名 |
| API Key | sk-你的密钥 | 账户与 API 密钥 页面创建 |
OpenAI 兼容
https://moxus.ai/v1
Anthropic 兼容
https://moxus.ai
Gemini 兼容
https://moxus.ai/v1beta
认证方式
OpenAI 格式：Authorization 头
大多数调用（chat、embeddings、images 等）使用此方式：
Authorization: Bearer sk-你的密钥
Bearer 首字母大写。Bearer 与密钥之间以单个空格分隔。
cURL 示例：
curl https://moxus.ai/v1/chat/completions \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "你好"}]
}'
Anthropic（Claude）格式：x-api-key 头
调用 Claude 原生接口 /v1/messages 时，使用 x-api-key 头：
curl https://moxus.ai/v1/messages \
-H "x-api-key: sk-你的密钥" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "你好"}]
}'
Gemini 格式
调用 Gemini 原生接口时，可使用 x-goog-api-key 头，或按 Google SDK 约定传递密钥（将密钥作为 Google API Key 使用）。
SDK 配置
Python（openai 库）
from openai import OpenAI
client = OpenAI(
api_key="sk-你的密钥",
base_url="https://moxus.ai/v1",
)
Node.js（openai 库）
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "sk-你的密钥",
baseURL: "https://moxus.ai/v1",
});
环境变量方式（推荐）
不要将密钥硬编码于源码，应从环境变量读取：
测试、生产、第三方客户端应分别创建独立密钥，并为每把密钥设置额度上限。这样出现异常消耗时可以单独禁用，不影响其他场景。
export ICEROCKY_API_KEY="sk-你的密钥"
export ICEROCKY_BASE_URL="https://moxus.ai/v1"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ICEROCKY_API_KEY"],
base_url=os.environ["ICEROCKY_BASE_URL"],
)
认证失败排查
| 现象 | 原因 | 处理方式 |
|---|
401 Unauthorized | 密钥错误、缺少 Bearer 前缀或密钥已禁用/过期 | 重新填写正确的密钥 |
403 Forbidden | 无访问权限（IP 限制或模型限制） | 检查密钥的 IP 与模型限制设置 |
insufficient quota | 余额或密钥额度已用尽 | 充值或调高密钥额度上限 |
| 客户端提示模型列表拉取失败 | Base URL 是否包含 /v1 | 分别尝试两种写法 |
安全提示
- API 密钥等同于账户余额的使用权限，不得外泄。
- 不得将密钥硬编码于前端代码或提交至公开代码仓库。
- 如怀疑密钥泄露，应立即删除并重新创建。
不要在浏览器前端直接调用接口并暴露 API 密钥。前端应用应通过自己的后端服务转发请求，或使用平台允许的受控客户端能力。
后续步骤
