利用ガイド

中国本土のユーザー向け: 中国本土のユーザーは https://toapis.cn を API エンドポイント (Base URL)としてご利用ください. 本ドキュメント内の例では https://toapis.com を https://toapis.cn に置き換えてください.

この GET API は認証されたアカウント自身のデータのみ読み取ります. メインアカウントにサブアカウントのアクセス権は自動付与されません. 管理者も自身のみ照会できます. モデル API キーとは異なるシステムアクセストークンを使用します.

システムアクセストークンの取得

コンソールにログインし, 設定のシステムアクセストークン欄で生成します. 再生成すると以前のトークンは無効になるため, 既存の連携も更新してください. この API は読み取り専用ですが, トークンは既存 API の権限を維持します. トークン自体が読み取り専用とは限りません.

Authorization ヘッダーは 1 つだけ送信します. cookie, URL の認証情報, モデル API キー, Agent トークン, MCP トークンは代用できません. X-User-Id は不要です. 任意の X-Locale は en, zh, zh-TW, ja, ko, ru に対応し, 未指定時はアカウント設定と言語ネゴシエーションに従います.

curl --request GET \
  --url 'https://toapis.com/api/v1/account' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

レスポンスと金額

成功時は HTTP 200, code=0, message="" です. エラーは実際の HTTP ステータスと数値コードを返します. 翻訳される message ではなく HTTP ステータスと code で判定してください. ID と金額は文字列, 時刻はタイムゾーン付き RFC 3339 です. 不明または対象外の値は契約に従い null になります.

残高と使用量の USD と credits は同じスナップショットから換算されます. 返された credits_per_usd を使い, 旧 API の換算率を固定しないでください. 支払額は元の通貨で表され, credits とは別です.

Cache-Control: private, no-store と X-Request-Id を返します. この ID は今回の照会を識別し, 使用量に含まれる元の生成リクエスト ID とは異なります.

{"code": 0, "message": "", "data": {"items": [], "has_more": false, "next_cursor": null, "meta": {}}}

ページ分割と時間範囲

一覧は data.items, has_more, next_cursor, meta を返します. 空の結果は [], 最終カーソルは null です. next_cursor を変更せず cursor に渡し, フィルターを維持します. 条件変更時は最初から取得し, カーソルを解析しないでください. 総件数は既定で計算しません.

時間範囲は UTC の半開区間 [from,to) です. 秒精度の保存値に対する境界は切り上げます. from と to は同時に指定し, 使用量では両方必須です. タスクは既定で直近 24 時間, 最大 31 日です. チャージと請求書は既定で 31 日, 最大 366 日です. 既定範囲は最初のページで固定され, 以後も時刻を省略できます. 不明なパラメータ, スカラーの重複, 不正なエスケープは 400 です.

レート制限とエラー

ユーザー全体で毎分 120 回です. 使用量集計は追加で毎分 6 回, 請求書一覧と詳細は別枠で毎分 6 回を共有します. 429 では Retry-After に従いランダムな待機時間を加えます. Redis 障害時, 軽量照会はノードごとに IP バケットとユーザーそれぞれ毎分 30 回になり, 集計と請求書は 503 を返します.

HTTP	code	対応
400	10004 / 13028	パラメータまたはカーソルを修正してください.
401	11032 / 11059	トークンの不足, 無効化, 再生成を確認してください.
403	11023 / 12001 / 12002 / 12006	状態と権限を確認してください. サブアカウントは請求を取得できません.
404	13001	存在しないか他人のリソースです.
429	10002	`Retry-After` に従い待機してください.
500	10000 / 13029	リクエスト ID を保存し内部エラーや換算設定を調査します.
503	11001 / 13030 / 13032	待機してください. 使用量のタイムアウト時は時間範囲を短くします.
409	15045	既存の対話フローで請求アカウントを関連付けます.
503	15046 / 15047	待機するかサポートに Stripe 設定と Customer 対応の確認を依頼します.

{
  "code": 10004,
  "message": "Invalid query parameters.",
  "data": {
    "param": "limit",
    "request_id": "request_example_query"
  }
}

データの範囲

使用量は変更される消費ログのスナップショットです. 精算や返金で過去の行が変わるため, 完全な純支出台帳ではありません. タスクは保存済みメタデータと確認済み課金のみで, 結果取得, 上流ポーリング, 精算, 返金は行いません. チャージに手動付与や独立したオフライン返金は含まれません. 請求書は現在確認済みの Stripe Customer のみ対象です.

GET	動作
`/api/v1/account`	アカウント情報の取得
`/api/v1/account/balance`	アカウント残高の取得
`/api/v1/account/api-keys`	API キー一覧の取得
`/api/v1/account/api-keys/{api_key_id}`	API キー詳細の取得
`/api/v1/account/usage/records`	使用量明細の取得
`/api/v1/account/usage/summary`	使用量集計の取得
`/api/v1/account/tasks`	アカウントタスク一覧の取得
`/api/v1/account/tasks/{task_id}`	アカウントタスク詳細の取得
`/api/v1/account/billing/topups`	チャージ注文一覧の取得
`/api/v1/account/billing/topups/{trade_no}`	チャージ注文詳細の取得
`/api/v1/account/billing/payment-method`	支払い方法の取得
`/api/v1/account/billing/auto-topup`	自動チャージ設定の取得
`/api/v1/account/billing/invoices`	請求書一覧の取得
`/api/v1/account/billing/invoices/{invoice_id}`	請求書詳細の取得

既存 API との関係

トークン残高, ユーザー残高, トークン作成の契約は変わりません. この API はシステムアクセストークンと code/message/data を使用します. タスク照会は生成結果の取得 API の代わりにはなりません.