個人アクセストークン

個人アクセストークンは、BeatAPI アカウントの操作を自動化するための認証情報です。アカウントの権限を持つため、スクリプトからタスクやテキストリクエストごとの費用などのアカウントデータを取得できます。モデル、タスク、ワークフローのリクエストには引き続き API キーを使用します。

個人アクセストークンと API キーの違い

作成、再発行、失効

1. ダッシュボードにサインインし、アカウントのセキュリティを開きます。
2. 個人トークンを作成を選び、本人確認を完了します。
3. トークンをコピーします。トークン全体を表示するのは今回だけで、画面を閉じるとページから削除されます。
4. 自動化を実行する環境に、BEATAPI_PERSONAL_TOKEN などのシークレットとして保存します。

個人トークンを再発行すると新しいトークンが発行され、以前のトークンは直ちに無効になります。個人トークンを失効するとトークンが削除され、使用しているツールは直ちにアクセスできなくなります。どちらの操作にも本人確認が必要です。トークンは信頼できるサーバーにのみ保管し、ブラウザーのコード、モバイルアプリ、共有リポジトリには含めないでください。

呼び出せるエンドポイント

トークンは Authorization: Bearer <token> で送信します。これらのエンドポイントには usage:read 権限が必要で、個人トークンにはこの権限が含まれています。利用記録の 2 つのエンドポイントは API キーで呼び出すと 403 forbidden を返します。GET /v1/usage は API キーとこのトークンのどちらでも呼び出せ、同じ集計を返します。今後、このトークンで呼び出せるアカウント用エンドポイントを追加していきます。

1 件のタスクを照合する

タスク作成時に返る data.id を保存し、次のように取得します。

curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"

{
  "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-<request ID> の場合は、その値でも取得できます。タスク作成リクエストのリクエスト ID で取得すると、タスク ID と同じ記録が返ります。

利用記録を一覧表示する

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"

{
  "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"
  }
}

has_more が true の間は、cursor を付けて次のページを取得します。不明なパラメーター、1〜100 の範囲外の limit、ミリ秒のタイムスタンプは無視されず、400 bad_request が返ります。

利用記録のフィールド

タスクの金額は、GET /v1/tasks/{task_id} が返す usage.credits_charged と usage.credits_refunded と一致します。タスクの精算額が予約額を上回るか下回る場合、記録には精算後の合計が表示されます。取得できるのは自分のアカウントの記録だけで、他のアカウントの ID には 404 not_found が返ります。

エラー

エラーは共通のエラーオブジェクトで返ります。