ドキュメント

ドキュメント

キーのグループ

クライアントごとに専用の API キーを発行してグループにまとめ、任意の期間について、クライアント別・キー別の利用額を確認し、各クライアントが 1 か月に使える額に上限を設けられます。アカウントも残高もひとつです。

グループはアカウント内の API キーのフォルダーで、たとえばクライアントごとにひとつ作ります(CID000001、CID000002)。グループ内のキーもほかのキーとまったく同じように API を呼び出せ、グループには独自の残高、チャージ、ログインはありません。グループには、所属するすべてのキーの合計に対する月間上限を設定できます。各キーが属するグループはひとつか、なしです。

グループの設定は三つの手順で

  • グループを作成する。API キーページで「新しいグループ」を選び、クライアントの名前を付けます。
  • キーを入れる。グループの見出しにある「新しいキー」を選ぶと、そのグループ内にキーを作成できます。既存のキーを入れるには、そのキーのメニューを開いて「グループに移動」を選びます。
  • 数字を読む。API キーページには、各キーの今月(暦月)の利用額と各グループの合計が表示されます。使用量ページでは同じキーがグループ別に表示され、今日、過去 7 日間・30 日間、今月、先月、または選んだ日付(最長 90 日)から期間を選べます。

ひと月分を確認してエクスポートする

使用量ページの上部で「先月」(または「今月」、日付を選ぶなら「カスタム」)を選びます。「APIキー別」では各グループの見出しにそのグループの利用額と呼び出し回数が表示されます。上部のグループメニューで、ページ全体をひとつのグループ(その数値、グラフ、モデル、呼び出し)に絞り込めます。「CSV をエクスポート」では、ページに表示されている内容(同じ期間、同じグループ)を、キー別または日別でダウンロードできます。

キー別のファイルはキーとグループの組み合わせごとに一行で、ファイル名は kunavo-cost-by-key_2026-10-01_2026-10-31.csv のような形式です。期間内に呼び出しのあったキー(失効済みを含む)を、各呼び出し時に属していたグループの下に載せ、さらに現在のグループで呼び出しのなかった有効なキーを 0 として載せるため、各クライアントのキー一覧が欠けることはありません。グループはダッシュボードと同じ順に並び、各グループ内のキーは利用額の多い順、グループ未設定のキーは最後です。日別のファイルは先頭に date 列があり、キーがあるグループで呼び出しを行った日ごとに一行です。

列内容
group呼び出し時に属していたグループ。どのグループにも属していなかった呼び出しは空欄です。その後削除されたグループは、名前の後ろに (deleted) が付きます。
key_nameキーの名前。
key_prefixダッシュボードに表示されるキーの先頭部分。キー全体が出力されることはありません。
key_statusactive または revoked。
calls期間内にそのキーで行われた呼び出しの回数。
errorsそのうち失敗した呼び出しの回数。失敗した呼び出しは無料です。
input_tokens入力トークン数(キャッシュの読み取りと書き込みを含む)。
output_tokens出力トークン数。
cached_input_tokens入力トークンのうち、プロンプトキャッシュから読み取られた分。
cache_write_tokens入力トークンのうち、プロンプトキャッシュに書き込まれた分。
cost_usd呼び出しに課金された金額(米ドル、小数点以下八桁)。
数式のように見える名前。=、+、-、@ で始まるグループ名やキー名は、先頭にアポストロフィを付けて出力します。これにより、スプレッドシートはそれを数式として実行せず、テキストとして表示します。

グループごとに月間の利用額に上限を設ける

API キーページでグループのメニューを開き、「月間上限を設定」を選びます。上限は、グループ内のすべてのキーが暦月(UTC)に使った合計額、つまり各キーがそのグループに属していた間の呼び出しで数えます。グループの利用額が上限を超えることになるリクエストは 402 で拒否され、料金は請求されません。空欄なら上限なし、0 ならキーを失効させずにグループ内のすべてのキーを一時停止します。

各キー自身の月間上限も引き続き適用され、先に達したほうがリクエストを拒否します。グループの見出しには今月の利用額と上限が表示され、リクエストの拒否が始まると「上限に到達」、上限が 0 のときは「一時停止中」と表示されます。

グループ、または独自の上限を設定したキーが月間上限の 80% を使ったとき、Kunavo はアカウントのメールアドレスにメールを送ります。上限によりリクエストの拒否が始まったときにも、もう一度送ります。どちらのメールも、上限ごとに月 1 回までです。

金額の数え方

  • 費用は課金された金額です。各呼び出しの費用は、完了時に残高から差し引かれた金額です。失敗した呼び出しは無料です。
  • 月と日は UTC 基準です。今月は 1 日の 00:00 UTC から始まります。たとえばヤンゴン(UTC+6:30)では、10 月は現地時間の 11 月 1 日 06:30 に終わります。使用量ページには、表示中の期間の日付が表示されます。
  • 呼び出しは、その時点でキーが属していたグループに集計されます。キーを別のグループに移動すると、移動後の呼び出しだけが新しいグループに集計され、それまでの呼び出しは元のグループに残ります。そのため、API キーページのグループの今月の合計は、現在その下に表示されているキーの合計と一致しないことがあります。
  • 失効したキーは元のグループに残ります。失効前に使った金額は引き続きそのグループの合計に含まれ、エクスポートにも出力されます。
  • 削除したグループの呼び出しは残ります。使用量ページとエクスポートでは、そのグループ名の下に「削除済み」として表示されたまま残り、同じ名前は新しいグループに使えます。
  • 三か所、同じ数字。同じ暦月について、API キーページのグループ合計、使用量ページの「今月」でのグループ合計、CSV のそのグループの行の合計は、セント単位まで一致します。

よくある質問

  • グループごとに残高がありますか?いいえ。すべてのグループがアカウントのひとつの残高を使います。あるクライアントの利用額を制限するには、そのクライアントのグループ、または各キーに月間上限を設定してください。
  • クライアントがログインして利用状況を見られますか?いいえ。グループが見えるのはあなただけです。各キーは GET /v1/usage で自身の使用量を取得できますが、そこにグループは含まれません。グループに月間上限がある場合、GET /v1/balance はそのキーに上限とグループ全体の今月の利用額を返しますが、グループ名は返しません。
  • グループを削除するとどうなりますか?キーをどうするか選べます。引き続き使えるようにして今後はグループ未設定にするか、グループと一緒に失効させるかです。どちらの場合も、それまでの呼び出しはグループ名の下に残ります。
  • キーをあるクライアントから別のクライアントに移すには?もう一方のクライアントのグループに移動してください。移動後の呼び出しはそちらに集計され、それまでの呼び出しは最初のクライアントに残ります。
  • これ以外の期間を見られますか?はい。使用量ページで「カスタム」を選び、最長 90 日を指定できます。プログラムからは、GET /v1/usage で同じ期間のひとつのキーの日別の費用を取得できます。

クライアントのキーの作成、グループ化、上限設定、失効を手作業ではなく自社のツールから行うには、管理 API を使ってください。管理キーは別の認証情報で、この API でのみ使えます。