> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # 個人アクセストークン > 権限と有効期限を選んで個人アクセストークンを作成し、API キーの管理、残高と支払いの取得、リクエストごとの利用記録（USD）の照合に使う方法を説明します。 # 個人アクセストークン 個人アクセストークンは、BeatAPI アカウントの操作を自動化するための認証情報です。トークンごとに付与する権限を選べるため、スクリプトには許可した操作だけを任せられます。残高の取得、API キーの管理、支払い履歴の取得、タスクやテキストリクエストごとの費用などのアカウントデータの取得ができます。モデル、タスク、ワークフローのリクエストには引き続き API キーを使用します。 ## 個人アクセストークンと API キーの違い | | 個人アクセストークン | API キー | | ------ | --------------------------------------------------------------- | --------------------------------------- | | 接頭辞 | `nap_` | `sk-` | | 用途 | `GET /v1/account` や `GET /v1/account/usage/records` などのアカウント自動化 | モデル、タスク、ワークフローのリクエスト | | 数 | アカウントあたり最大 20 個。それぞれに名前を付けます | 必要な数だけ作成可能 | | 制限 | 選択した権限。モデル、IP、利用額の個別制限はありません | キーごとにモデル、IP、利用額を制限可能 | | 有効期限 | 任意：7、30、90、365 日、または無期限 | キーごとに有効期限を設定可能 | | 利用できる先 | `/v1/account` 配下のエンドポイントと `GET /v1/usage` | モデル、タスク、ワークフローのエンドポイントと `GET /v1/usage` | ## トークンの作成と管理 1. [ダッシュボード](https://beatapi.io/dashboard/security)にサインインし、**アカウントのセキュリティ**を開きます。 2. **個人トークンを作成**を選び、名前を入力し、必要な権限にチェックを入れ、有効期限（7、30（既定）、90、365 日、または無期限）を選びます。 3. 本人確認を完了してからトークンをコピーします。トークン全体を表示するのは今回だけで、画面を閉じるとページから削除されます。 4. 自動化を実行する環境に、`BEATAPI_PERSONAL_TOKEN` などのシークレットとして保存します。 1 つのアカウントには最大 20 個のトークンを作成できます。使用場所が分かる名前を付け、必要な権限だけを付与してください。トークン一覧には、各トークンの名前、権限、有効期限、最終使用日時が表示されます。 トークン名は本人確認なしでいつでも変更できます。権限の変更とトークンの失効には本人確認が必要です。変更した権限は同じトークンにそのまま適用されるため、再デプロイは不要です。**失効**するとトークンが削除され、使用しているツールは直ちにアクセスできなくなります。トークンは信頼できるサーバーにのみ保管し、ブラウザーのコード、モバイルアプリ、共有リポジトリには含めないでください。 複数トークンに対応する前に作成したトークンは、それまでの権限のまま引き続き使用できます。 ## 権限 トークンには、チェックを入れた権限だけが付与されます。トークンにない権限が必要な呼び出しは `403 forbidden` で拒否され、メッセージに不足している権限名が示されます。 | 権限 | できること | エンドポイント | | ---------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | | `usage:read` | 利用記録と利用状況の集計を取得 | `GET /v1/account/usage/records`、`GET /v1/account/usage/records/{id}`、`GET /v1/usage` | | `api_key:read` | API キーの一覧取得と取得（キーはマスク表示） | `GET /v1/account/keys`、`GET /v1/account/keys/{id}` | | `api_key:write` | API キーの作成（キー全体は 1 回だけ返却）、編集、無効化、削除 | `POST /v1/account/keys`、`PATCH /v1/account/keys/{id}`、`DELETE /v1/account/keys/{id}` | | `api_key:reveal` | 既存の API キーのキー全体を取得 | `POST /v1/account/keys/{id}/reveal` | | `wallet:read` | 支払い（チャージ）履歴を取得 | `GET /v1/account/payments` | | `profile:read` | プロフィール、残高、通知設定を取得 | `GET /v1/account`、`GET /v1/account/notifications` | | `profile:write` | 通知設定を変更 | `PATCH /v1/account/notifications` | トークンでは、残高のチャージ、サインインやセキュリティ設定の変更、他のトークンの管理はできません。これらはダッシュボードでのみ行えます。`api_key:reveal` は、キー全体の取得が本当に必要なトークンにだけ付与してください。 ## 呼び出せるエンドポイント トークンは `Authorization: Bearer ` で送信します。各エンドポイントには表に示す権限が必要です。 | エンドポイント | 権限 | 用途 | | ------------------------------------ | ---------------- | --------------------------------------- | | `GET /v1/account` | `profile:read` | アカウントのプロフィールと USD 残高 | | `GET /v1/account/notifications` | `profile:read` | 残高通知の設定を取得 | | `PATCH /v1/account/notifications` | `profile:write` | 通知の種類、しきい値、メールアドレスを変更 | | `GET /v1/account/payments` | `wallet:read` | 支払いを新しい順に一覧表示 | | `GET /v1/account/keys` | `api_key:read` | API キーを新しい順に一覧表示 | | `GET /v1/account/keys/{id}` | `api_key:read` | 1 件の API キーを取得 | | `POST /v1/account/keys` | `api_key:write` | API キーを作成 | | `PATCH /v1/account/keys/{id}` | `api_key:write` | API キーの編集、無効化、再有効化 | | `DELETE /v1/account/keys/{id}` | `api_key:write` | API キーを削除 | | `POST /v1/account/keys/{id}/reveal` | `api_key:reveal` | API キーのキー全体を取得 | | `GET /v1/account/usage/records` | `usage:read` | 課金されたリクエストを新しい順に一覧表示 | | `GET /v1/account/usage/records/{id}` | `usage:read` | タスク ID またはリクエスト ID で 1 件の記録を取得 | | `GET /v1/usage` | `usage:read` | アカウントの集計と内訳。[クイックスタート](/quick-guide)を参照 | `/v1/account` 配下のエンドポイントは API キーで呼び出すと `403 forbidden` を返します。`GET /v1/usage` は API キーと `usage:read` 権限付きのトークンのどちらでも呼び出せ、同じ集計を返します。レスポンスは `data` に格納されます。ID は文字列、時刻は Unix 秒、金額は USD です。一覧は `object`、`data`、`has_more`、`next_cursor` を返し、`limit`（1～100、既定 20）と `cursor` を指定できます。未知のクエリーパラメーターは `400 bad_request` で拒否されます。 ## 残高を取得する `profile:read` 権限が必要です。 ```bash curl https://api.beatapi.io/v1/account \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "account", "id": "1042", "username": "ada", "display_name": "Ada", "email": "ada@example.com", "credit_balance": 42.5, "currency": "USD" } } ``` ## API キーを一覧表示する `api_key:read` 権限が必要です。キーはマスクされ、先頭の数文字である `key_prefix` だけが返されます。1 件のキーを取得するには `GET /v1/account/keys/{id}` を使用します。 ```bash curl -G https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "api_key", "id": "1287", "title": "production", "key_prefix": "sk-Ab3d", "status": "active", "created_at": 1793200000, "last_used_at": 1793247312, "expires_at": null, "remaining_credits": null, "credits_used": 18.42, "models": [], "allowed_ips": [] } ], "has_more": false } } ``` ## API キーを作成する `api_key:write` 権限が必要です。必須なのは `title` だけです。`expires_at`（Unix 秒）、`remaining_credits`（USD）、`models`、`allowed_ips` は任意で、省略すると期限なし、利用額の上限なし、全モデル、すべての IP アドレスが対象になります。キー全体が返るのはこのレスポンスの `key` だけで、以降の取得では `key_prefix` しか返らないため、今すぐ保存してください。 ```bash curl -X POST https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "ci-runner", "remaining_credits": 20, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"]}' ``` ```json { "data": { "object": "api_key", "id": "1304", "title": "ci-runner", "key_prefix": "sk-Qm8R", "key": "sk-Qm8RExampleFullKeyShownOnlyInThisResponse", "status": "active", "created_at": 1793250000, "last_used_at": null, "expires_at": null, "remaining_credits": 20, "credits_used": 0, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"] } } ``` キーの編集は `PATCH /v1/account/keys/{id}` で行い、`title`、`status`（`active` または `disabled`）、`expires_at`（`null` で無期限）、`remaining_credits`（`null` で上限なし）、`models`（`[]` で全モデル）、`allowed_ips` のいずれかを送信します。`DELETE /v1/account/keys/{id}` は `object`、`id`、`deleted: true` を返します。 ## API キーのキー全体を取得する `api_key:reveal` 権限が必要です。`api_key:read` とは別の権限で、キーを一覧表示できるトークンでも、この権限を付与しない限りキー全体は取得できません。 ```bash curl -X POST https://api.beatapi.io/v1/account/keys/1287/reveal \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "api_key_secret", "id": "1287", "key": "sk-Ab3dExampleFullKey" } } ``` ## 支払いを一覧表示する `wallet:read` 権限が必要です。`status` は `paid`（既定）、`pending`、`failed`、`expired`、`reviewing`、`all` から選びます。`currency` は支払い通貨で、`USD` または `CNY` です。`credits` はこの支払いで加算される残高（USD）です。 ```bash curl -G https://api.beatapi.io/v1/account/payments \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "status=paid" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "payment", "id": "5531", "order_no": "ORD20261027153012", "status": "paid", "amount_paid": 20, "currency": "USD", "credits": 20, "payment_method": "stripe", "created_at": 1793100000, "paid_at": 1793100042 } ], "has_more": false } } ``` ## 通知のしきい値を変更する `profile:write` 権限が必要です。設定を `GET /v1/account/notifications` で取得するには `profile:read` が必要です。`type`（`email` または `none`）、`threshold_credits`、`notification_email` のいずれかを送信します。利用によって残高がしきい値を下回ると BeatAPI が通知します。`0` を指定すると既定値になります。レスポンスは更新後の設定で、`effective_threshold_credits` が実際に適用されるしきい値です。 ```bash curl -X PATCH https://api.beatapi.io/v1/account/notifications \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"threshold_credits": 5}' ``` ```json { "data": { "object": "notification_settings", "type": "email", "threshold_credits": 5, "effective_threshold_credits": 5, "default_threshold_credits": 1, "notification_email": "billing@example.com", "account_email": "ada@example.com" } } ``` ## 1 件のタスクを照合する タスク作成時に返る `data.id` を保存し、次のように取得します。 ```bash curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "usage_record", "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ", "type": "image", "model": "seedream-5-pro", "task_id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ", "request_id": "202610290330051234567893f9a1c2eXy7Kp2Qd", "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" }, "status": "succeeded", "created_at": 1793244605, "currency": "USD", "credits_charged": 0.06, "credits_refunded": 0, "usage": { "images": 2 } } } ``` テキストリクエストでは、レスポンスヘッダー `X-BeatAPI-Request-Id` のリクエスト ID を使用します。テキストのレスポンスボディの `id` が `chatcmpl-` の場合は、その値でも取得できます。タスク作成リクエストのリクエスト ID で取得すると、タスク ID と同じ記録が返ります。 ## 利用記録を一覧表示する ```bash curl -G https://api.beatapi.io/v1/account/usage/records \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "start=2026-10-01T00:00:00Z" \ --data-urlencode "end=2026-11-01T00:00:00Z" \ --data-urlencode "limit=100" ``` ```json { "data": { "object": "list", "data": [ { "object": "usage_record", "id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw", "type": "text", "model": "deepseek-v4.1-flash", "request_id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw", "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" }, "status": "succeeded", "created_at": 1793247312, "currency": "USD", "credits_charged": 0.002468, "credits_refunded": 0, "usage": { "input_tokens": 1200, "output_tokens": 350, "cached_tokens": 1024 } } ], "has_more": true, "next_cursor": "eyJ0IjoxNzkzMjQ3MzEyLCJpIjo5ODc2NTQzMn0" } } ``` | パラメーター | 説明 | | ------------ | ------------------------------------------------------------------ | | `start` | 含める最も古い `created_at`。Unix 秒または RFC 3339（例: `2026-10-01T00:00:00Z`） | | `end` | 上限（この値は含みません）。形式は `start` と同じです | | `model` | 公開モデル ID（例: `seedream-5-pro`） | | `type` | `text`、`image`、`video`、`workflow`、`data`、`realtime`、`other` のいずれか | | `api_key_id` | API キーの数値 ID（`api_key.id` と同じ） | | `limit` | 1 ページの件数。1〜100 で、既定値は 20 です | | `cursor` | 前のページの `next_cursor` | `has_more` が `true` の間は、`cursor` を付けて次のページを取得します。不明なパラメーター、1〜100 の範囲外の `limit`、ミリ秒のタイムスタンプは無視されず、`400 bad_request` が返ります。 ## 利用記録のフィールド | フィールド | 説明 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `object` | `usage_record` | | `id` | タスクの場合はタスク ID、それ以外はリクエスト ID | | `type` | `text`、`image`、`video`、`workflow`、`data`、`realtime`、`other` | | `model` | 公開モデル ID | | `task_id` | タスクの場合のみ | | `request_id` | 記録を作成したリクエストのリクエスト ID（判明している場合） | | `api_key` | 支払いに使われた API キーの `id`、`title`、`key_prefix`。ダッシュボードのお試し利用では `null` | | `status` | `queued`、`processing`、`succeeded`、`failed`。料金が全額返金された場合は `refunded` | | `created_at` | Unix 秒 | | `currency` | `USD` | | `credits_charged` | 割引と精算を反映した支払額（USD）。小数点以下最大 6 桁 | | `credits_refunded` | 残高に返金された金額（USD） | | `usage` | 課金対象の数量。テキストは `input_tokens`、`output_tokens`、`cached_tokens`、`cache_write_tokens`、メディアは `images`、`seconds`、`resolution` | タスクの金額は、`GET /v1/tasks/{task_id}` が返す `usage.credits_charged` と `usage.credits_refunded` と一致します。タスクの精算額が予約額を上回るか下回る場合、記録には精算後の合計が表示されます。取得できるのは自分のアカウントの記録だけで、他のアカウントの ID には `404 not_found` が返ります。 ## エラー | ステータス | `code` | 発生する場合 | | ----- | -------------- | ---------------------------------------------------------------------- | | `400` | `bad_request` | クエリーパラメーターまたはリクエストボディのフィールドが無効、または未知のパラメーターがある | | `401` | `unauthorized` | トークンがない、不明、失効済み、または期限切れ | | `403` | `forbidden` | トークンにエンドポイントが必要とする権限がない（メッセージに権限名が示される）、またはアカウント用エンドポイントに API キーが送信された | | `404` | `not_found` | アカウントにその ID の記録、支払い、API キーがない | エラーは共通の[エラーオブジェクト](/errors)で返ります。