> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证

> 本文档说明如何通过 API 密钥对请求进行认证。认证是所有程序化调用的前提。

本文档说明如何通过 API 密钥对请求进行认证。认证是所有程序化调用的前提。

## 认证机制

Moxus AI通过 API 密钥（Bearer Token）识别请求来源。每次请求须在 HTTP 头中携带密钥，平台据此验证身份、权限与余额。缺少或错误的密钥将导致请求被拒绝（返回 401）。

<Info>
  OpenAI 兼容请求使用 `Authorization: Bearer sk-你的密钥`。Anthropic 原生接口也可使用 `x-api-key: sk-你的密钥`。
</Info>

## 基础信息

| 项目       | 值                                | 来源                                               |
| -------- | -------------------------------- | ------------------------------------------------ |
| Base URL | `https://moxus.ai/v1`（OpenAI 格式） | 平台访问域名                                           |
| API Key  | `sk-你的密钥`                        | [账户与 API 密钥](/zh/platform/account-and-keys) 页面创建 |

不同协议的 Base URL：

<Columns cols={3}>
  <Card title="OpenAI 兼容" icon="message-square-code">
    `https://moxus.ai/v1`
  </Card>

  <Card title="Anthropic 兼容" icon="braces">
    `https://moxus.ai`
  </Card>

  <Card title="Gemini 兼容" icon="sparkles">
    `https://moxus.ai/v1beta`
  </Card>
</Columns>

## 认证方式

### OpenAI 格式：Authorization 头

大多数调用（chat、embeddings、images 等）使用此方式：

```text theme={null}
Authorization: Bearer sk-你的密钥
```

注意事项：

* `Bearer` 首字母大写。
* `Bearer` 与密钥之间以单个空格分隔。

cURL 示例：

```bash theme={null}
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` 头：

```bash theme={null}
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 库）

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://moxus.ai/v1",
)
```

### Node.js（openai 库）

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的密钥",
  baseURL: "https://moxus.ai/v1",
});
```

### 环境变量方式（推荐）

不要将密钥硬编码于源码，应从环境变量读取：

<Tip>
  测试、生产、第三方客户端应分别创建独立密钥，并为每把密钥设置额度上限。这样出现异常消耗时可以单独禁用，不影响其他场景。
</Tip>

```bash theme={null}
export ICEROCKY_API_KEY="sk-你的密钥"
export ICEROCKY_BASE_URL="https://moxus.ai/v1"
```

```python theme={null}
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 密钥等同于账户余额的使用权限，不得外泄。
* 不得将密钥硬编码于前端代码或提交至公开代码仓库。
* 如怀疑密钥泄露，应立即删除并重新创建。

<Warning>
  不要在浏览器前端直接调用接口并暴露 API 密钥。前端应用应通过自己的后端服务转发请求，或使用平台允许的受控客户端能力。
</Warning>

详见 [账户与 API 密钥 - 密钥安全实践](/zh/platform/account-and-keys#密钥安全实践)。

## 后续步骤

* 实现流式输出：参阅 [流式输出](/zh/guide/streaming)。
* 调用工具：参阅 [函数调用](/zh/guide/function-calling)。