管理 API

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

概覽

Management API 用於查詢組織餘額、自動化管理組織級 API Key，並查詢單個 Key 維度的用量與帳單，而不需要使用一般的推理 API Key。管理令牌可在控制台的設定頁面產生與輪換：

Authorization: Bearer mt-your-management-token

管理令牌不是推理 API Key。mt-... 用於 /v1/management/*，sk-... 用於 /v1/responses 等模型推理介面。

可用介面

介面	方法	說明
`/v1/management/balance`	GET	查詢目前組織餘額彙總
`/v1/management/api-keys`	GET	列出目前組織下的使用者 API Key
`/v1/management/api-keys`	POST	建立新的使用者 API Key
`/v1/management/api-keys/{keyId}`	PATCH	更新名稱、額度、模型白名單、過期時間或狀態
`/v1/management/api-keys/{keyId}/usage`	GET	查詢指定 Key 的分頁用量明細
`/v1/management/api-keys/{keyId}/billing`	GET	查詢指定 Key 的聚合帳單拆分結果

用量篩選

GET /v1/management/api-keys/{keyId}/usage 支援以下 query 參數：

參數	型別	預設值 / 限制	說明
`page`	integer	預設 `1`，最小 `1`	從 1 開始的頁碼
`limit`	integer	預設 `50`，最小 `1`，最大 `100`	每頁筆數
`model`	string	最大長度 `100`	請求時使用的模型名稱
`modelVendor`	string	最大長度 `100`	公開模型供應商
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	起始時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD`
`endDate`	string	-	結束時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD`

如果同時提供 startDate 與 endDate，則 startDate 必須早於或等於 endDate。

API Key 請求體

POST /v1/management/api-keys

欄位	型別	預設值 / 限制	說明
`name`	string	必填，預設 `Default Key`，長度 `1-50`	顯示名稱，伺服器端會先去除前後空白
`limitAmount`	number \| null	最小 `0`，輸入上限 `1000000`	`null` 或省略 = 不限額，`0` = 零額度，正數會被規範化為一個儲存上限，且不能超過 `100000` USD 等值
`limitCurrency`	列舉	預設 `USD`	僅限 USD。傳送 `CNY` 會回傳 `400 currency_retired`。
`models`	string[]	預設 `[]`	可選的模型白名單
`expiresAt`	string \| null	RFC3339 datetime	`null` 表示沒有到期時間

PATCH /v1/management/api-keys/

欄位	型別	預設值 / 限制	說明
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	長度 `1-50`	更新後的顯示名稱
`limitAmount`	number \| null	最小 `0`，輸入上限 `1000000`	`null` = 不限額，`0` = 零額度，正數會被規範化為一個儲存上限，且不能超過 `100000` USD 等值
`limitCurrency`	列舉	預設 `USD`	僅限 USD。傳送 `CNY` 會回傳 `400 currency_retired`。
`models`	string[]	-	更新後的模型白名單
`expiresAt`	string \| null	RFC3339 datetime	`null` 表示移除過期時間

PATCH 請求至少需要提供一個欄位。

金額欄位

管理 API 的金額請求與回應欄位僅支援 USD。
limitCurrency 預設為 USD；傳送 CNY 會回傳 400 currency_retired。

報表語義

model 指的是呼叫方請求的模型名稱。
modelVendor 指的是公開模型供應商，而不是隱藏的實體路由。
scene 是由 endpoint 或任務型別推導出的公開請求場景。

介面只會回傳公開可理解的 billing 與 reporting 欄位，不會暴露內部 routing 細節或實體渠道中繼資料。

/usage 的逐條明細會在底層請求完成結算後包含 billing_transaction_id。建議使用 request_id + billing_transaction_id 做請求級對帳。

帳單分頁說明

/usage 是分頁介面；/billing 目前回傳的是聚合帳單拆分結果，不會回傳 page / limit 形式的分頁資訊。若你需要逐筆記錄，請優先使用 /usage。

快速範例

先用目前的管理令牌查詢組織餘額：

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

然後列出這個組織下可見的 API Keys：

curl "https://api.tokenlab.sh/v1/management/api-keys" \
  -H "Authorization: Bearer mt-your-management-token"

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

核心

文字

檔案與批次

圖像

音訊與即時

音樂

視頻與素材

Worlds

3D

非同步任務

Gemini 原生

管理

概覽

可用介面

用量篩選

API Key 請求體

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

金額欄位

報表語義

帳單分頁說明

快速範例

下一步

​概覽

​可用介面

​用量篩選

​API Key 請求體

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​金額欄位

​報表語義

​帳單分頁說明

​快速範例

​下一步

概覽

可用介面

用量篩選

API Key 請求體

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

金額欄位

報表語義

帳單分頁說明

快速範例

下一步