管理 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 を使わずに、組織残高の取得、組織 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`	1 ページあたりの件数
`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` = 利用可能額 0、正の値は保存時に正規化され、`100000` USD 相当を超えません
`limitCurrency`	enum	既定 `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` = 利用可能額 0、正の値は保存時に正規化され、`100000` USD 相当を超えません
`limitCurrency`	enum	既定 `USD`	USD のみです。`CNY` を送信すると `400 currency_retired` が返されます。
`models`	string[]	-	更新後のモデル許可リスト
`expiresAt`	string \| null	RFC3339 datetime	`null` は有効期限を解除します

PATCH リクエストでは少なくとも 1 つのフィールドを指定する必要があります。

金額フィールド

Management API の金額リクエストおよびレスポンスフィールドは USD のみをサポートします。
limitCurrency の既定値は USD です。CNY を送信すると 400 currency_retired が返されます。

レポートの意味

model は、呼び出し元が要求した公開 model を指します。
modelVendor は、隠れた互換ルートではなく、公開 model vendor を指します。
scene は、endpoint または task type から導出される公開リクエストシーンです。

レスポンスには公開可能な Billing / Reporting 項目のみが含まれ、非公開のプロバイダー詳細は公開されません。

/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/

金額フィールド

レポートの意味

請求のページネーションに関する注意

クイック例

次のステップ