メインコンテンツへスキップ

API 概要

Token 管理 API を使うと、キーごとにコンソールを操作する代わりに、コードから API キーのライフサイクル全体を管理できます。 最も一般的なユースケースは一括発行です。各チームメンバー、下流の顧客、またはプロジェクトにそれぞれ専用のキーを付与し、利用可能な金額、呼び出し可能なモデル、有効期間を個別に設定できます。 スケジュールされたジョブと組み合わせれば、各キーに毎日自動でリセットされる予算を設定することもできます。

クォータ制限

remain_quota このキーで利用できる合計金額を制限します

モデル制限

models 許可リストを設定します。リストに含まれないモデルへの呼び出しは拒否されます

有効期限の制限

expired_time 有効期限のタイムスタンプを設定します。この日時を過ぎると、キーは機能しなくなります
キーが1つか2つだけ必要な場合は、コンソールを使うほうが手早いです。API キーの作成方法をご覧ください。この API は、自動発行、スケジュールされたキーのローテーション、または独自のシステムへのキー管理の統合を目的としています。

パーソナルアクセス token の取得方法

Token 管理 API は、パーソナルアクセス token(nap_で始まる)で認証を行いますが、これは API キーとは異なります。
1

パーソナルアクセス tokens を開く

api.apiyi.com/account/profileのプロフィールページに移動します。アカウントオプション配下の Personal Access Tokens → Create Token をクリックします。
2

必要な Model keys の権限を選択する

3つの権限は独立しています。使用するもののみを選択してください:一括発行スクリプトには3つすべてが必要です。使用状況監視スクリプトには Read のみが必要です。
3

有効期限と IP 許可リストを設定する

デフォルトの有効期限は30日間であるため、より長い期間を設定することをお勧めします。発行スクリプトが固定 IP を持つサーバー上で動作する場合は、IP 許可リストの設定を強く推奨します。許可リストは作成後に編集できないため、まずは許可リストなしでスクリプトの動作を確認し、その後、許可リストを設定した本番用の別の token を作成してください。
パーソナルアクセス token の作成:名前、有効期限、IP 許可リスト、権限
Write および Reveal secret 権限を持つ token は、モデルを呼び出す API キーを作成できます。アカウントのパスワードと同様に取り扱ってください。パーソナルアクセス token 自体はモデルを呼び出すことはできませんが、呼び出し可能なキーを発行できます。このような token にはIP 許可リストを設定し、コード内ではなくシークレットマネージャーに保存し、リポジトリには絶対にコミットせず、有効期限が切れる前に更新してください。
レガシーなシステム tokens は 2026-11-11 (UTC+8) に廃止予定です。 「アカウントオプション - システム token」配下で生成された AccessTokens は、その日まで引き続き機能します。その日付以降は 401 ACCESS_TOKEN_LEGACY_RETIRED を返します。 使用状況を確認した上で期日を延長する可能性もありますが、今すぐパーソナルアクセス token に切り替えることをお勧めします。切り替える際は、スクリプトも確認してください。作成エンドポイントはマスクされた key を返すようになりました。プレーンテキストを取得するには、以下で説明するように POST /api/token/{id}/key を呼び出してください。 パーソナルアクセス token とは? を参照してください。

エンドポイント

すべてのエンドポイントで認証方法は共通です。Authorization ヘッダーにパーソナルアクセストークンを設定します。 Bearer プレフィックスは任意です。 ベース URL は https://api.apiyi.com です。

Tokenの作成

リクエスト例

リクエストフィールド

unlimited_quota はデフォルトで false、remain_quota はデフォルトで 0 です — 両方を省略するとクォータがゼロの token が生成され、使用できません。remain_quota を明示的に設定するか、unlimited_quota を true に設定してください。
モデルの許可リストには models フィールドを使用してください。レスポンス構造には model_limits、model_limits_enabled、allow_ips も含まれます。 これらを渡してもエラーは発生せず、エンドポイントは 200 を返しますが、現時点では効果がなく、token を再取得しても未設定の状態で表示されます。利用可能なモデルを制限するには models を使用してください。送信元IP制限は、現時点ではご自身側で実装する必要があります。

レスポンス例

レスポンス内の key はマスクされており、直接使用することはできません。 平文を取得するには、レスポンスの id を使用して平文取得エンドポイントを呼び出してください。

キーの平文を取得する

  • パーソナルアクセストークンにはModel keys · Reveal secretの権限が必要です。ない場合は403 ACCESS_TOKEN_SCOPE_DENIEDが返されます。
  • 返されるkeyには**sk-プレフィックスが含まれていません**。ご自身で先頭に付加してください。上記の例では、実際のAPIキーはsk-K1RPzapu…になります。
  • 取得後はすぐに保存し、安全なチャネル経由で配布してください。レスポンスボディをログファイルに残さないようにしてください。

一括作成

サーバー側の一括エンドポイントはありません — リクエストボディに count などを渡しても効果はなく、単一の token のみが作成されます。一括発行はクライアント側でループ処理を行って実行します。
1人のユーザーが保持できるのは最大 1,000 tokens です。 これはアカウント全体の上限であり、削除されずに無効化されている token もカウントされます。上限に達すると、作成エンドポイントは失敗します — スロットを解放するために、使用しなくなった token を削除してください。一括実行を行う前に、GET /api/token/?p=0&page_size=100 をページングして既存の数量を確認してください。キーをローテーションする際は、「新しいキーの作成 → トラフィックの移行 → 古いキーの無効化 → 呼び出しが残っていないことを確認して削除」という最後の手順まで確実に完了させてください。削除せずに無効化するだけではスロットが占有されたままになるため、数回のローテーションサイクルで上限に達してしまいます。

3つの制限の使用

クォータ制限

remain_quotaは、tokenが使用できる金額に上限を設定します。換算方法は 残高照会APIと一致します。

換算ルール

500,000クォータ = $1.00 USD
たとえば、下流の顧客に上限が$10のキーを発行するには、remain_quotaを 5000000に設定し、unlimited_quotaをfalseに設定します。これまでの使用量は、tokenの used_quotaフィールドで確認できます。 remain_quotaは一度限りの合計値で、自動的に補充されません。毎日の予算を設定するには、以下のシナリオ:キーごとの制限を毎日自動的にリセットするをご覧ください。

モデル制限

modelsは、カンマ区切りの許可リストです。設定すると、リストにないモデルの呼び出しは拒否されます。
レスポンスはHTTP 403となり、課金は発生しません。modelsを省略すると、制限は適用されません。

有効期限の制限

expired_timeはUnix秒単位のタイムスタンプで、-1は期限なしを意味します。たとえば、30日後に 期限切れとなるキーは次のように設定します。

tokenの一覧表示

主要なフィールド:

token の更新

更新エンドポイントには完全なオブジェクトが必要です。パッチではありません。正しい流れは次のとおりです: GET 完全な token オブジェクトを取得し、変更したいフィールドを修正してから、 PUT オブジェクト全体 を送り返します。変更したフィールドだけを送ると、残りはクリアされます。

シナリオ: 毎日自動でリセットされるキーごとの上限

会社がワークフロー、チームメンバー、または下流プロジェクトにキーを渡す場合、よくある要件は 「各キーの1日の利用額を$5までに制限し、翌日に上限をリセットする」ことです。ワークフローが 暴走しても、損害は1日分の予算に抑えられます。 プラットフォームにはまだ「日次クォータ」フィールドが組み込まれていませんが、上記の更新エンドポイントと 深夜に1回実行するスケジュールジョブを組み合わせれば実現できます。毎日、対象のキーのremain_quotaを日次上限に戻します。 キー自体は変更されないため、チームメンバーは同じキーを使い続けられます。 その日の予算を使い切ると、呼び出しは拒否され(課金されません)。深夜の リセット後、再び利用できるようになります。
1

個人用アクセストークンを準備する

モデルキー · 読み取りとモデルキー · 書き込みを付与します。「シークレットを表示」は必要ありません。 スクリプトを固定IPのサーバーで実行する場合は、トークンにIP許可リストを設定します。
2

制限するキーと日次上限の一覧を作成する

一覧表示エンドポイントで各キーのidを確認し、以下のスクリプトのDAILY_BUDGET_USDに入力します。
3

スクリプトを毎日00:00(UTC+8)に実行する

cron、クラウド関数のタイマー、または任意のスケジューラーを使用できます。詳細は以下をご覧ください。

リセットスクリプト

スクリプトでは、さらに次の3つの処理を行います。
  • 二重リセットを防止: 1日に2回実行されても(スケジューラーのキャッチアップ実行や手動での再実行など)、翌日分の予算を重複して付与しません
  • 超過分を翌日に繰り越し: クォータはソフトキャップのため(下記参照)、昨日の超過分を今日のクォータから差し引き、長期的に日次平均が上限内に収まるようにします。この処理を無効にするには、CARRY_OVERDRAFTをFalseに設定します
  • 昨日の使用額を出力: 実行ごとに、前の期間に各キーが使用した金額をログに記録するため、ログを簡易的な日次レポートとしても使えます。

スケジューリング

自分だけが読み取れる環境ファイルに token を保存し、cron でスクリプトを毎日実行します。
別のタイムゾーンで「1日」を定義するには、cron の時刻とスクリプト内の TZ の両方を変更します。

利用する前に知っておくべきこと

クォータはソフトキャップであり、厳密な制限ではありません。 クォータのチェックはリクエスト開始時に行われるため、複数の同時実行リクエストが同時に制限を通過することがあります。また、1回の高額なリクエスト(動画、4K画像、非常に長いコンテキスト)で一気に上限を超え、残高がマイナスになることもあります。同時実行数と単価が高いほど、超過幅も大きくなります。スクリプトは超過分を翌日に繰り越して差し引きます。絶対に上限を超えてはならないキーがある場合は、独自に同時実行数を制御するか、models 許可リストを使って高額なモデルを除外してください。
  • リセット時は上書きされ、加算されません:未使用の予算は翌日に繰り越されません。また、コンソールでこれらのキーのクォータを手動で変更しても、次回のリセット時に上書きされます
  • 午前0時前後に処理中のリクエスト:午前0時前に送信したリクエストが午前0時以降に完了すると、新しい日の分として課金される場合があります。通常、その金額はわずかです
  • スクリプトが実行されないと、キーは枯渇したままです:呼び出しは一時的にブロックされますが、追加で消費されることはありません。スケジュール済みジョブに失敗時のアラートを追加してください
  • アカウント残高が引き続き最上位の制限です:キーの日次上限の合計がアカウント残高を超える場合、先に残高が尽き、すべてのキーが停止します
  • 今日だけ特定のキーに少し多く割り当てる必要がありますか? 更新エンドポイントでそのキーのremain_quotaを引き上げてください。翌日には通常どおり上限に戻ります

無効化と削除

無効化(記録は保持されます)

無効化すると、キーは直ちに動作しなくなります — そのキーを使った呼び出しは 401 を返します — ただし token の記録とその利用履歴は保持されます。

削除(元に戻せません)

一括削除も同様にクライアント側のループです:
削除は元に戻せません。key を一時的に停止したいだけなら、代わりに無効化してください — 利用履歴は照合用に引き続き利用できます。

よくある質問

作成エンドポイントはマスクされたkey(途中に*が連続して含まれます)を返すため、そのままでは使用できません。 返されたidを指定してPOST /api/token/{id}/keyを呼び出すと、プレーンテキストを取得できます(Reveal secret権限が必要です)。 その後、sk-を先頭に付けてください。以前のスクリプトで作成レスポンスのkeyを直接使用している場合は、パーソナルアクセストークンに切り替える際にこの手順を追加してください。
作成時にremain_quotaが設定されておらず、unlimited_quotaもtrueに設定されていなかった可能性が高いです。 このデフォルトの組み合わせでは、クォータがゼロのtokenが作成されます。2つのうちいずれかを明示的に指定して、再作成してください。
これらのフィールドは、model_limits_enabledと同様、現在は反映されません。指定してもエラーにはなりませんが、保存されません。利用可能なモデルを制限するにはmodelsを使用してください。送信元IPの制限は、現時点ではご自身の側で設定する必要があります。
サーバー側に一括作成エンドポイントはなく、リクエストボディでcountのような値を渡しても反映されません。代わりにクライアント側で作成リクエストをループしてください。上記の一括作成のセクションをご覧ください。
ユーザーごとに最大1,000個です。無効化されていても、削除されていないtokenは合計数に含まれます。 上限に達すると、不要なtokenを削除するまで新規作成できません。キーをローテーションする際は、最後に削除の手順を行ってください。無効化するだけでは枠が空きません。
組み込みの日次クォータフィールドはありませんが、スケジュールされたジョブで実現できます。毎日00:00 (UTC+8)に、更新エンドポイントを呼び出して各キーのremain_quotaを日次上限に戻してください。キー自体は変更されません。予算を使い切るとリクエストは拒否され、課金されませんが、翌日には再び使用できるようになります。 スクリプト全体と注意事項については、上記のシナリオ:キーごとの日次上限を自動でリセットするをご覧ください。
更新エンドポイントではオブジェクト全体を指定する必要があります。まずオブジェクト全体をGETし、変更を加えてから、変更したフィールドだけを送信するのではなく、全体をPUTしてください。
無効化(status: 2)するとキーはすぐに使えなくなりますが、レコードと使用履歴は保持され、いつでも1に戻せます。削除は取り消せず、レコードも削除されます。一時的に利用を停止する場合は、無効化をおすすめします。
tokenのused_quotaフィールドには、そのキーの累計支出額が記録されています(÷ 500,000 = USD)。期間ごとの内訳や呼び出し単位の詳細を確認するには、コンソールのログページでtoken名を指定して絞り込んでください。呼び出し履歴を確認する方法もご覧ください。

重要な注意事項

パーソナルアクセストークンは API キーではなく、両者に互換性はありません
  • API キー(sk- で始まります)は /v1/* 推論エンドポイント用です
  • パーソナルアクセストークン(nap_ で始まります)は /api/* 管理エンドポイント用であり、モデルを呼び出すことはできません
エラーリファレンス:401 ACCESS_TOKEN_LEGACY_RETIRED は、廃止されたレガシーシステムトークンをまだ使用していることを意味します。 401 This access token may not be used from the current IP address. は、トークンのホワイトリスト外の IP からリクエストが送信されたことを意味します。 403 ACCESS_TOKEN_SCOPE_DENIED は、このエンドポイントに必要な権限がトークンに不足していることを意味します(エンドポイント一覧表を参照してください)。
平文キーの取り扱いにご注意ください平文取得エンドポイントは、モデルを直接呼び出すことができるキーを返します。そのため、以下の点にご注意ください。
  • key を含むレスポンスボディをログファイルに記録したり、リポジトリにコミットしたりしないでください
  • キーをチームメンバーに配布する際は、グループチャットではなく安全なチャネルを使用してください
  • この平文には sk- プレフィックスが付いていないため、一般的なシークレットスキャナーで検出されない可能性があります — 自動チェックによる検出に依存しないでください
運用のヒント
  • 一括作成する際は、瞬間的な高い同時実行数を避けるため、呼び出し間に適度な遅延を設けてください
  • 後でログ内で token_name ごとに使用状況を特定できるよう、各キーにわかりやすい name(team-alice や prod-webhook など)を付けてください
  • ローテーションの場合:新しいキーを作成し、トラフィックを移行させ、古いキーを無効化してしばらく観察し、呼び出しが残っていないことを確認してから削除してください

関連ドキュメント