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

# 认证与额度

> 认证系统 API 请求，并正确换算账号余额和 API Key 额度。

## 概述

系统 API 用于管理 MixRoute 账号中的资源，包括 API Key、智能路由 Key 和钱包操作。它与模型推理 API 相互独立。

| 用途         | Base URL                     | 使用的凭证               |
| ---------- | ---------------------------- | ------------------- |
| 账号与 Key 管理 | `https://api.mixroute.ai`    | 系统访问令牌              |
| 模型推理       | `https://api.mixroute.ai/v1` | 以 `sk-` 开头的 API Key |

<Warning>
  系统访问令牌拥有账号级管理权限。请勿将其放入浏览器代码、移动应用、日志或源代码仓库。
</Warning>

## 获取系统访问令牌

在 [MixRoute 控制台](https://console.mixroute.ai/settings)打开 **账号设置 → API 访问**，生成并复制系统访问令牌，然后将其保存到密钥管理系统。

<Warning>
  `GET /api/user/token` 会生成新的系统访问令牌。这是轮换操作，不是查询操作，并会使旧令牌失效。日常自动化中不要调用该接口。
</Warning>

设置后续示例使用的环境变量：

```bash theme={null}
export BASE_URL="https://api.mixroute.ai"
export ACCESS_TOKEN="YOUR_SYSTEM_ACCESS_TOKEN"
export USER_ID="YOUR_NUMERIC_USER_ID"
```

数字用户 ID 可在账号设置页面中查看。

## 认证请求头

每个受保护的系统 API 请求都必须携带以下两个请求头：

```http theme={null}
Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN
New-Api-User: YOUR_NUMERIC_USER_ID
```

发送 JSON 请求体时，还需要：

```http theme={null}
Content-Type: application/json
```

用户 ID 必须属于该系统访问令牌。认证失败并不总是使用同一个 HTTP 状态码：缺少凭证或用户 ID 不匹配时可能返回 HTTP `401`，而无效的系统访问令牌目前会返回 HTTP `200` 和 `success: false`。客户端必须同时检查 HTTP 状态码和响应结构。

可使用以下只读请求验证认证配置：

```bash theme={null}
curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -e '
      if .success == true then .data
      else error(.message // "authentication failed")
      end
    '
```

## 响应结构

多数系统 API 使用统一响应结构：

```json theme={null}
{
  "success": true,
  "message": "",
  "data": {}
}
```

部分参数校验和认证错误会返回 HTTP `200` 和 `success: false`，因此客户端需要同时检查 HTTP 状态码与 `success` 字段。

```bash theme={null}
response=$(curl -fsS "$BASE_URL/api/user/self/groups" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

jq -e '.success == true' <<< "$response" >/dev/null || {
  jq -r '.message // "System API request failed"' <<< "$response" >&2
  exit 1
}
```

## 额度单位

账号余额和 API Key 额度使用内部额度单位存储，并不直接等于美元。请从公开状态接口读取当前换算系数：

```bash theme={null}
quota_per_unit=$(curl -fsS "$BASE_URL/api/status" \
  | jq -er '.data.quota_per_unit')

usd_amount=20
internal_quota=$((usd_amount * quota_per_unit))
printf 'Quota for $%s: %s\n' "$usd_amount" "$internal_quota"
```

换算公式如下：

```text theme={null}
内部额度 = 美元金额 × quota_per_unit
美元金额 = 内部额度 ÷ quota_per_unit
```

<Note>
  `quota_per_unit` 是部署配置，可能发生变化。客户端应动态读取，不要写死当前数值。
</Note>

### 账号余额与 Key 额度

* 账号余额来自 `GET /api/user/self` 的 `quota` 字段，是账号可用的钱包余额。
* Key 额度由 `remain_quota` 表示，是单个 API Key 的消费上限。
* 给 Key 设置额度不会从钱包中转移或冻结资金。
* `unlimited_quota: true` 只表示没有 Key 级额度上限，请求仍会消耗账号余额。

读取并换算当前账号余额：

```bash theme={null}
user=$(curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

quota_per_unit=$(curl -fsS "$BASE_URL/api/status" \
  | jq -er '.data.quota_per_unit')

jq --argjson unit "$quota_per_unit" '{
  user_id: .data.id,
  internal_quota: .data.quota,
  balance_usd: (.data.quota / $unit)
}' <<< "$user"
```

## 可用分组

创建 Key 前，应读取当前账号可选择的分组：

```bash theme={null}
curl -fsS "$BASE_URL/api/user/self/groups" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq '.data'
```

不要假设其他账号的分组也对当前账号开放。本教程中的通用示例使用 `default` 分组。

## 安全检查清单

* 系统访问令牌只能保存在服务端。
* 自动化任务应使用独立账号或独立凭证。
* 不要记录显示完整 Key 接口的响应。
* 尽量为每个 API Key 设置明确名称、过期时间、额度和 IP 限制。
* 轮换时先创建替代 Key，迁移流量后再停用并删除旧 Key。