利用方法
公開 API では自分のアカウントデータの取得と通常のモデルキーの管理ができます. 親アカウントに子アカウントのデータ参照権限が自動付与されることはありません. 管理者も自分のリソースのみ操作できます.
公開 API では自分のアカウントデータの取得と通常のモデルキーの管理ができます. 親アカウントに子アカウントのデータ参照権限が自動付与されることはありません. 管理者も自分のリソースのみ操作できます.
国際版は https://api.toapis.com, 中国本土版は https://api.toapis.cn を使用します. この API グループには Web サイトのルートドメインを使用しないでください.
システムアクセストークンの取得
アカウント設定でシステムアクセストークンを生成します. 再生成すると古いトークンは無効になるため, 連携先も更新してください.
すべてのリクエストで Authorization ヘッダーに Bearer YOUR_SYSTEM_ACCESS_TOKEN を付け, ヘッダーは 1 つだけ送信します. モデル API キー (sk-...), cookie, URL の認証情報, Agent/MCP トークンは身份として使えず, X-User-Id も不要です.
システムアクセストークンはキーの書き込みも可能で, 読み取り専用ではない点に注意してください.
任意ヘッダー X-Locale は en, zh, zh-TW, ja, ko, ru を受け付けます. 有効な値がない場合はアカウントの言語設定とネゴシエーション結果が使われ, リクエストがアカウント設定を初期化することはありません.
結果の判定は HTTP ステータスと数値 code で行い, 言語によって変わる message は比較しないでください.
curl https://api.toapis.com/api/v1/account \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'レスポンスと金額
すべてのレスポンスのトップレベルは code, message, data の 3 フィールドのみです. 成功時は code=0, message="" で, HTTP ステータスは通常の成功が 200, キー作成が 201, Webhook テストのキュー登録とファイル削除の受理が 202 です.
失敗時は実際の HTTP ステータスが保持され, エラーの data は param, params, request_id または null のみで内部詳細は公開しません.
リソース ID と金額は十進文字列で, Webhook の api_key_id は整数です. 時刻はタイムゾーン付き RFC 3339 で, 不明または該当しない値はフィールドの定義に従い null を返します. 残高と使用量は USD と credits の両方で返し, 換算にはレスポンスの credits_per_usd を使います.
支払い金額は元の通貨のままです.
すべてのレスポンスに Cache-Control: private, no-store と X-Request-Id ヘッダーが付きます. X-Request-Id は今回の API リクエストを識別するもので, 使用量 trace に記録された元の生成リクエスト ID とは別物です.
{
"code": 0,
"message": "",
"data": {
"items": [],
"has_more": false,
"next_cursor": null,
"meta": {}
}
}ページ分割と期間
ユーザーファイル一覧を除き, 一覧は data.items, has_more, next_cursor, meta を返します. 空の一覧は items が [], 最終ページは next_cursor が null で, 総件数は返しません. 次ページを取るときは next_cursor をそのまま cursor に渡し, 絞り込み条件は変えないでください.
条件を変えたら先頭から取り直します.
期間は UTC の半開区間 [from, to) で, 秒単位の境界は切り上げます. 既定と上限はエンドポイントごとに異なります: 使用量は全ページで from と to が必須で最長 31 日, タスクは既定で直近 24 時間・最長 31 日, チャージと請求書は既定で直近 31 日・最長 366 日です.
既定期間は最初のページで確定するため, 以降のページでは省略できます. 未知または重複したパラメータ, 不正なエスケープは 400 です.
期間は UTC の半開区間 [from,to) で, 秒単位の境界は切り上げます. 使用量では全ページで from と to が必須で, 最大 31 日です. タスクは既定 24 時間, 最大 31 日, チャージと請求書は既定 31 日, 最大 366 日です. 既定期間は初回に固定され, 次ページも省略できます.
未知のパラメータ, 重複した単一値, 不正なエスケープは 400 です.
レート制限とエラー
読み取りはユーザーごとに毎分 120 回の上限を共有します. 使用量集計, 請求書, 料金にはそれぞれ追加で毎分 6 回の制限があり, 請求書の一覧と詳細は同じ上限を共有します.
API キー, Webhook, ユーザーファイルの書き込みは別枠のユーザーごと毎分 10 回を共有し, 読み取り枠は消費しません. システムアクセストークンの再生成で制限はリセットされず, 新旧の互換パスも同じ上限を共有します.
リクエストの頻度や同時実行数が多い場合は 429 になることがあります. Retry-After にランダムな遅延を加えて再試行してください. 503 はサービスの一時的な利用不可を示します. 頻度を下げ, タイムアウトした作成, ローテーション, 削除のリクエストを無条件に再送しないでください.
| HTTP | code | 対応 |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | 本文, パラメータ, カーソルを修正します. |
| 401 | 11032 / 11059 | システムアクセストークンを確認します. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | アカウント状態, 権限, キーのグループを確認します. |
| 404 | 13001 / 16008 | 対象が存在しないか他のアカウントに属します. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | キー数, 有効期限, 残高, 請求先の関連付けを確認します. |
| 429 | 10002 | Retry-After に従って待機します. |
| 500 | 10000 / 13029 | 調査用に request_id を保存します. |
| 503 | 11001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029 | 待機し, 必要に応じて使用量の期間を狭めます. |
データの範囲
親アカウントは自分のデータのみを参照でき, メンバー (子アカウント) のデータは含まれず, 子アカウントは請求を参照できません. 使用量レコードは消費ログのライブスナップショットで, 後続の確定処理や返金で変化するため最終的な純支出とは一致しません.
タスク API が返すのは保存済みのタスクメタデータと確認可能な課金のみで, 生成結果の取得, 上流へのポーリング, 精算, 返金は行いません. チャージには手動付与のクレジットと独立したオフライン返金は含まれず, 請求書は現在検証済みの Stripe Customer のみが対象です.
リソース ID にはキー一覧や詳細に含まれる数値 id を使い, シークレット文字列 (sk-...) は使えません. 完全なシークレットが返るのは作成とローテーションのレスポンスの一度きりで, 以降の読み取りでは返りません. 書き込み成功は設定の保存を意味しますが, 反映には少し時間がかかる場合があります.
キーの無効化, ローテーション, 失効により処理中のリクエストやタスクが失敗することがあります. タスクの自動取消や返金は行われず, 新旧シークレットが同時に有効な期間もありません.
エンドポイント
主要パスは以下のとおりです. 互換性のため残された旧 /api/v1/account/... GET パスと移行方法は 変更履歴を参照してください.
ユーザーファイル API は登録済みファイル, 保持期間, 非同期削除を管理します. ファイル一覧はページ分割の例外で, items, next_cursor のみを返し, 最終カーソルは "" で has_more と meta はありません. 削除受理は HTTP 202 です. 保持設定と削除はアカウント書き込み枠を共有します. ユーザー保持期限はプラットフォーム自動削除が有効な場合のみ適用されますが, 手動削除は独立です. 範囲と例は下記を参照してください.
| HTTP | |
|---|---|
GET /api/v1/account | アカウント情報の取得 |
GET /api/v1/account/balance | アカウント残高の取得 |
GET /api/v1/api-keys | API キー一覧の取得 |
GET /api/v1/api-keys/{api_key_id} | API キー詳細の取得 |
GET /api/v1/api-keys/{api_key_id}/balance | キーの残高を取得 |
POST /api/v1/api-keys | API キーを作成 |
PATCH /api/v1/api-keys/{api_key_id} | API キーを更新 |
DELETE /api/v1/api-keys/{api_key_id} | API キーを失効 |
POST /api/v1/api-keys/{api_key_id}/rotate | API キーをローテーション |
GET /api/v1/webhook | Webhook 設定の取得 |
PATCH /api/v1/webhook | Webhook 設定の更新 |
POST /api/v1/webhook/rotate-secret | Webhook 署名シークレットの更新 |
POST /api/v1/webhook/test | Webhook のテスト |
GET /api/v1/webhook/events | Webhook イベント一覧 |
GET /api/v1/webhook/events/{event_id} | Webhook イベントの取得 |
GET /api/v1/usage/records | 使用量明細の取得 |
GET /api/v1/usage/summary | 使用量集計の取得 |
GET /api/v1/tasks | アカウントタスク一覧の取得 |
GET /api/v1/tasks/{task_id} | アカウントタスク詳細の取得 |
GET /api/v1/billing/topups | チャージ注文一覧の取得 |
GET /api/v1/billing/topups/{trade_no} | チャージ注文詳細の取得 |
GET /api/v1/billing/payment-method | 支払い方法の取得 |
GET /api/v1/billing/auto-topup | 自動チャージ設定の取得 |
GET /api/v1/billing/stripe/invoices | 請求書一覧の取得 |
GET /api/v1/billing/stripe/invoices/{invoice_id} | 請求書詳細の取得 |
GET /api/v1/pricing | モデル料金を取得 |
GET /api/v1/user/file | ユーザーファイル一覧 |
GET /api/v1/user/file/retention | ファイル保持期間の取得 |
PUT /api/v1/user/file/retention | ファイル保持期間の設定 |
POST /api/v1/user/file/deletion-requests | ファイル削除リクエストの作成 |
GET /api/v1/user/file/deletion-requests/{id} | ファイル削除進捗の取得 |
Webhook
接続順序:
POST /api/v1/webhook/rotate-secretで署名シークレットを生成して受信側に保存します.PATCH /api/v1/webhookでコールバック URL を設定して有効化します.POST /api/v1/webhook/testでテストイベントを送信するか, イベント一覧で配信結果を確認します.
署名検証のルールと全手順はWebhook 設定の取得を参照してください.