> ## 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。