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 を作成してください。

エンドポイント
すべてのエンドポイントで認証方法は共通です。Authorization ヘッダーにパーソナルアクセストークンを設定します。
Bearer プレフィックスは任意です。
ベース URL は
https://api.apiyi.com です。
Tokenの作成
リクエスト例
リクエストフィールド
レスポンス例
キーの平文を取得する
- パーソナルアクセストークンにはModel keys · Reveal secretの権限が必要です。ない場合は403
ACCESS_TOKEN_SCOPE_DENIEDが返されます。 - 返される
keyには**sk-プレフィックスが含まれていません**。ご自身で先頭に付加してください。上記の例では、実際のAPIキーはsk-K1RPzapu…になります。 - 取得後はすぐに保存し、安全なチャネル経由で配布してください。レスポンスボディをログファイルに残さないようにしてください。
一括作成
サーバー側の一括エンドポイントはありません — リクエストボディにcount などを渡しても効果はなく、単一の token のみが作成されます。一括発行はクライアント側でループ処理を行って実行します。
- Python
- Node.js
- cURL
3つの制限の使用
クォータ制限
remain_quotaは、tokenが使用できる金額に上限を設定します。換算方法は
残高照会APIと一致します。
換算ルール
500,000クォータ = $1.00 USD
remain_quotaを
5000000に設定し、unlimited_quotaをfalseに設定します。これまでの使用量は、tokenの
used_quotaフィールドで確認できます。
remain_quotaは一度限りの合計値で、自動的に補充されません。毎日の予算を設定するには、以下のシナリオ:キーごとの制限を毎日自動的にリセットするをご覧ください。
モデル制限
modelsは、カンマ区切りの許可リストです。設定すると、リストにないモデルの呼び出しは拒否されます。
modelsを省略すると、制限は適用されません。
有効期限の制限
expired_timeはUnix秒単位のタイムスタンプで、-1は期限なしを意味します。たとえば、30日後に
期限切れとなるキーは次のように設定します。
tokenの一覧表示
token の更新
シナリオ: 毎日自動でリセットされるキーごとの上限
会社がワークフロー、チームメンバー、または下流プロジェクトにキーを渡す場合、よくある要件は 「各キーの1日の利用額を$5までに制限し、翌日に上限をリセットする」ことです。ワークフローが 暴走しても、損害は1日分の予算に抑えられます。 プラットフォームにはまだ「日次クォータ」フィールドが組み込まれていませんが、上記の更新エンドポイントと 深夜に1回実行するスケジュールジョブを組み合わせれば実現できます。毎日、対象のキーのremain_quotaを日次上限に戻します。
キー自体は変更されないため、チームメンバーは同じキーを使い続けられます。
その日の予算を使い切ると、呼び出しは拒否され(課金されません)。深夜の
リセット後、再び利用できるようになります。
1
個人用アクセストークンを準備する
モデルキー · 読み取りとモデルキー · 書き込みを付与します。「シークレットを表示」は必要ありません。
スクリプトを固定IPのサーバーで実行する場合は、トークンにIP許可リストを設定します。
2
制限するキーと日次上限の一覧を作成する
一覧表示エンドポイントで各キーの
idを確認し、以下のスクリプトのDAILY_BUDGET_USDに入力します。3
スクリプトを毎日00:00(UTC+8)に実行する
cron、クラウド関数のタイマー、または任意のスケジューラーを使用できます。詳細は以下をご覧ください。
リセットスクリプト
- 二重リセットを防止: 1日に2回実行されても(スケジューラーのキャッチアップ実行や手動での再実行など)、翌日分の予算を重複して付与しません
- 超過分を翌日に繰り越し: クォータはソフトキャップのため(下記参照)、昨日の超過分を今日のクォータから差し引き、長期的に日次平均が上限内に収まるようにします。この処理を無効にするには、
CARRY_OVERDRAFTをFalseに設定します - 昨日の使用額を出力: 実行ごとに、前の期間に各キーが使用した金額をログに記録するため、ログを簡易的な日次レポートとしても使えます。
スケジューリング
自分だけが読み取れる環境ファイルに token を保存し、cron でスクリプトを毎日実行します。TZ の両方を変更します。
利用する前に知っておくべきこと
- リセット時は上書きされ、加算されません:未使用の予算は翌日に繰り越されません。また、コンソールでこれらのキーのクォータを手動で変更しても、次回のリセット時に上書きされます
- 午前0時前後に処理中のリクエスト:午前0時前に送信したリクエストが午前0時以降に完了すると、新しい日の分として課金される場合があります。通常、その金額はわずかです
- スクリプトが実行されないと、キーは枯渇したままです:呼び出しは一時的にブロックされますが、追加で消費されることはありません。スケジュール済みジョブに失敗時のアラートを追加してください
- アカウント残高が引き続き最上位の制限です:キーの日次上限の合計がアカウント残高を超える場合、先に残高が尽き、すべてのキーが停止します
- 今日だけ特定のキーに少し多く割り当てる必要がありますか? 更新エンドポイントでそのキーの
remain_quotaを引き上げてください。翌日には通常どおり上限に戻ります
無効化と削除
無効化(記録は保持されます)
無効化すると、キーは直ちに動作しなくなります — そのキーを使った呼び出しは 401 を返します — ただし token の記録とその利用履歴は保持されます。削除(元に戻せません)
削除は元に戻せません。key を一時的に停止したいだけなら、代わりに無効化してください —
利用履歴は照合用に引き続き利用できます。
よくある質問
作成時に返されたキーが機能しないのはなぜですか?
作成時に返されたキーが機能しないのはなぜですか?
作成エンドポイントはマスクされた
key(途中に*が連続して含まれます)を返すため、そのままでは使用できません。
返されたidを指定してPOST /api/token/{id}/keyを呼び出すと、プレーンテキストを取得できます(Reveal secret権限が必要です)。
その後、sk-を先頭に付けてください。以前のスクリプトで作成レスポンスのkeyを直接使用している場合は、パーソナルアクセストークンに切り替える際にこの手順を追加してください。新しく作成したtokenでクォータ不足と表示されるのはなぜですか?
新しく作成したtokenでクォータ不足と表示されるのはなぜですか?
作成時に
remain_quotaが設定されておらず、unlimited_quotaもtrueに設定されていなかった可能性が高いです。
このデフォルトの組み合わせでは、クォータがゼロのtokenが作成されます。2つのうちいずれかを明示的に指定して、再作成してください。model_limitsやallow_ipsが反映されないのはなぜですか?
model_limitsやallow_ipsが反映されないのはなぜですか?
これらのフィールドは、
model_limits_enabledと同様、現在は反映されません。指定してもエラーにはなりませんが、保存されません。利用可能なモデルを制限するにはmodelsを使用してください。送信元IPの制限は、現時点ではご自身の側で設定する必要があります。1回のリクエストで複数のtokenを作成できますか?
1回のリクエストで複数のtokenを作成できますか?
サーバー側に一括作成エンドポイントはなく、リクエストボディで
countのような値を渡しても反映されません。代わりにクライアント側で作成リクエストをループしてください。上記の一括作成のセクションをご覧ください。1つのアカウントで保持できるtokenの数はいくつですか?
1つのアカウントで保持できるtokenの数はいくつですか?
ユーザーごとに最大1,000個です。無効化されていても、削除されていないtokenは合計数に含まれます。
上限に達すると、不要なtokenを削除するまで新規作成できません。キーをローテーションする際は、最後に削除の手順を行ってください。無効化するだけでは枠が空きません。
各キーの1日あたりの支出額に上限を設定し、翌日にリセットできますか?
各キーの1日あたりの支出額に上限を設定し、翌日にリセットできますか?
組み込みの日次クォータフィールドはありませんが、スケジュールされたジョブで実現できます。毎日00:00 (UTC+8)に、更新エンドポイントを呼び出して各キーの
remain_quotaを日次上限に戻してください。キー自体は変更されません。予算を使い切るとリクエストは拒否され、課金されませんが、翌日には再び使用できるようになります。
スクリプト全体と注意事項については、上記のシナリオ:キーごとの日次上限を自動でリセットするをご覧ください。更新後に他のフィールドがクリアされました
更新後に他のフィールドがクリアされました
更新エンドポイントではオブジェクト全体を指定する必要があります。まずオブジェクト全体を
GETし、変更を加えてから、変更したフィールドだけを送信するのではなく、全体をPUTしてください。無効化と削除の違いは何ですか?
無効化と削除の違いは何ですか?
無効化(
status: 2)するとキーはすぐに使えなくなりますが、レコードと使用履歴は保持され、いつでも1に戻せます。削除は取り消せず、レコードも削除されます。一時的に利用を停止する場合は、無効化をおすすめします。各キーの支出額を確認するにはどうすればよいですか?
各キーの支出額を確認するにはどうすればよいですか?
tokenの
used_quotaフィールドには、そのキーの累計支出額が記録されています(÷ 500,000 = USD)。期間ごとの内訳や呼び出し単位の詳細を確認するには、コンソールのログページでtoken名を指定して絞り込んでください。呼び出し履歴を確認する方法もご覧ください。重要な注意事項
運用のヒント
- 一括作成する際は、瞬間的な高い同時実行数を避けるため、呼び出し間に適度な遅延を設けてください
- 後でログ内で
token_nameごとに使用状況を特定できるよう、各キーにわかりやすいname(team-aliceやprod-webhookなど)を付けてください - ローテーションの場合:新しいキーを作成し、トラフィックを移行させ、古いキーを無効化してしばらく観察し、呼び出しが残っていないことを確認してから削除してください
関連ドキュメント
- 呼び出し履歴の確認方法 — コンソールでのキーごとの呼び出し詳細および料金
- 残高照会 API — アカウントの残高
- API キーの作成方法 — コンソールでの手動作成
- トークンとグループ — グループの役割と選択方法