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

# 认证说明

> 了解如何使用 API Key 进行身份认证

## API Key 认证

启航 AI API 使用 API Key 进行身份认证。所有 API 请求都需要在 HTTP 请求头中包含有效的 API Key。

## 获取 API Key

1. 登录 [启航 AI 控制台](https://api.qhaigc.net/v1)
2. 导航到 **API 令牌** 页面
3. 点击 **创建新令牌** 按钮
4. 为令牌设置一个描述性名称(可选)
5. 复制生成的 API Key 并妥善保存

<Warning>
  API Key 只会在创建时显示一次,请务必立即保存。如果丢失,需要重新生成新的 API Key。
</Warning>

## 使用 API Key

### 请求头方式

在所有 API 请求中,将 API Key 添加到 `Authorization` 请求头:

```bash theme={null}
Authorization: Bearer sk-your-api-key-here
```

### 完整示例

<CodeGroup>
  ```python Python theme={null}
  import openai

  # 方式 1: 设置 API Key
  client = openai.OpenAI(
      api_key="sk-your-api-key-here",
      base_url="https://api.qhaigc.net/v1"
  )

  # 方式 2: 使用环境变量
  import os
  os.environ["OPENAI_API_KEY"] = "sk-your-api-key-here"
  os.environ["OPENAI_BASE_URL"] = "https://api.qhaigc.net/v1"

  client = openai.OpenAI()
  ```

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

  // 方式 1: 直接设置
  const client = new OpenAI({
    apiKey: 'sk-your-api-key-here',
    baseURL: 'https://api.qhaigc.net/v1'
  });

  // 方式 2: 使用环境变量
  // 设置环境变量: OPENAI_API_KEY=sk-your-api-key-here
  // 设置环境变量: OPENAI_BASE_URL=https://api.qhaigc.net/v1
  const client = new OpenAI();
  ```

  ```bash cURL theme={null}
  curl https://api.qhaigc.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk-your-api-key-here" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```java Java theme={null}
  import com.theokanning.openai.service.OpenAiService;

  OpenAiService service = new OpenAiService("sk-your-api-key-here");
  // 注意: 需要配置 base_url 为 https://api.qhaigc.net/v1
  ```
</CodeGroup>

## 安全最佳实践

### 1. 使用环境变量

<Tip>
  **推荐做法**: 将 API Key 存储在环境变量中,而不是硬编码在代码里。
</Tip>

```bash .env theme={null}
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.qhaigc.net/v1
```

### 2. 不要提交到版本控制

确保 `.env` 文件和包含 API Key 的配置文件添加到 `.gitignore`:

```bash .gitignore theme={null}
.env
config.json
secrets.yaml
```

### 3. 定期轮换 API Key

建议定期更换 API Key,特别是在以下情况:

* 怀疑 API Key 可能已泄露
* 团队成员离职
* 每 3-6 个月进行一次常规轮换

### 4. 使用不同的 API Key

为不同的应用或环境使用独立的 API Key:

* 开发环境使用独立的 Key
* 生产环境使用独立的 Key
* 不同项目使用不同的 Key

这样可以:

* 更好地追踪使用情况
* 限制单个 Key 的影响范围
* 方便撤销特定 Key

### 5. 限制 API Key 权限

在控制台中,您可以为每个 API Key 设置:

* 使用配额限制
* IP 白名单(如适用)
* 允许访问的模型范围

## 验证 API Key

您可以通过调用以下接口验证 API Key 是否有效:

```bash theme={null}
curl https://api.qhaigc.net/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"
```

如果 API Key 有效,将返回可用模型列表。

## 错误处理

### 401 Unauthorized

如果收到 `401 Unauthorized` 错误,可能的原因:

1. **API Key 无效或已过期**
   * 检查 API Key 是否正确复制
   * 确认 API Key 未被撤销

2. **请求头格式错误**
   * 确保使用 `Bearer` 前缀
   * 检查是否有多余的空格或换行符

3. **Base URL 配置错误**
   * 确认使用 `https://api.qhaigc.net/v1`
   * 注意不要遗漏 `/v1` 路径

### 示例错误响应

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

## 查看 API Key 信息

您可以通过以下接口查看当前 API Key 的相关信息:

```bash theme={null}
curl https://api.qhaigc.net/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-your-api-key-here"
```

## 相关资源

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/docs/quickstart">
    查看完整的快速开始指南
  </Card>

  <Card title="API 参考" icon="code" href="/docs/api-reference/introduction">
    浏览所有 API 接口文档
  </Card>
</CardGroup>