残高とキーの利用上限

コンテンツを生成するリクエストの料金は、すべて前払いの USD 残高から支払われます。API キーごとに、使える金額を制限することもできます。このページでは、残高とキーの利用上限を読み取る方法と、そのどちらかが原因でリクエストが拒否されたときの対処を説明します。

どちらのエンドポイントも、Authorization: Bearer で送る API キーが必要です。認証を参照してください。

GET /v1/balance は、アカウントの残高を返します。

curl "https://api.sakuranbo.ai/v1/balance" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

レスポンスには、次のフィールドがあります。

• available_micro_usd と available_usd は、新しいリクエストに使える金額です。
• held_micro_usd と held_usd は、実行中のリクエストが確保している金額です。

各金額は 2 通りで返ります。micro USD（1 USD = 1,000,000 micro USD）の整数と、USD の 10 進文字列です。

残高を追加するには、ダッシュボードの入金ページを開きます。料金と課金を参照してください。

Sakuranbo AI は、料金がかかるリクエストを受理すると、一定の金額を確保します。確保した金額は available から held に移ります。リクエストが終わると、実際の料金が課金され、差額は available に戻ります。キャンセルされた、拒否された、またはモデルが出力を何も生成する前に失敗したリクエストは、確保した金額がすべて戻り、課金されません。モデルが出力（推論の出力を含みます）を生成し始めたあとにチャットのストリームが途切れたときは、生成された出力を含めてリクエストが課金され、確保した金額の残りは available に戻ります。チャットを参照してください。

まれに、画像または動画のジョブが、モデルの提供元が受け取ったかどうかを Sakuranbo AI が確認できないまま失敗することがあります。その場合、ジョブは upstream_error で failed になります。確保した金額は、課金されるかどうかを Sakuranbo AI が確認するまで held に残り、自動では available に戻りません。held に残ったままのときは、ジョブ ID を添えてサポートにお問い合わせください。

確保があるため、リクエストの実行中は、available が残高の合計より小さくなることがあります。新しいリクエストは、available に対して確認されます。

利用上限は、1 つの API キーに付きます。ダッシュボードのAPI キーページでキーを作成するときに設定します。上限は、USD の金額と期間で指定します。期間は none, day, month のいずれかです。

• day: キーが UTC の暦日 1 日に使える金額です。カウンターは、UTC の 0 時から数え直します。
• month: UTC の暦月 1 か月の金額です。カウンターは、毎月 1 日の UTC 0 時から数え直します。
• none: キーの通算の金額です。カウンターは数え直されません。

上限のないキーは、残高の許す範囲でいくらでも使えます。それでも利用額は集計されます。キーに有効期限を設定することもできます。期限切れのキーを使ったリクエストは 401 を返します。認証を参照してください。

ダッシュボードの Playground で実行するリクエストは API キーを使わないため、どのキーの上限にも含まれません。

GET /v1/key は、リクエストを送ったキーを、その上限と利用状況とともに返します。

curl "https://api.sakuranbo.ai/v1/key" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/key", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/key",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

レスポンスには、次のフィールドがあります。

• limit は、キーに上限がないときは null です。上限があるときは、金額と期間が入ります。
• usage.used_micro_usd と usage.used_usd は、実行中のリクエストが確保している金額と、現在の期間にすでに課金された金額の合計です。
• usage.remaining_micro_usd と usage.remaining_usd は、上限までの残りの金額です。キーに上限がないときは null です。
• usage.resets_at は、カウンターが数え直される時刻です。期間が none のときは null です。

リクエストは、2 つの場合に 402 で拒否されます。どちらかは error.details.limit_source で見分けます。

limit_source が balance の balance_insufficient: available の残高が、リクエストが確保する必要のある金額より小さい場合です。error.details には、requested_micro_usd、available_micro_usd、shortfall_micro_usd と、同じ 3 つの金額を USD にした requested_usd、available_usd、shortfall_usd が入ります。残高を追加して、リクエストをもう一度送ってください。

limit_source が key の key_limit_exceeded: キーの利用額に、リクエストが確保する必要のある金額を足すと、キーの上限を超える場合です。ちょうど上限に達するリクエストは受理されます。error.details には、period、resets_at、requested_micro_usd、limit_micro_usd、used_micro_usd と、同じ 3 つの金額を USD にしたものが入ります。両方に当てはまるときは、キーの上限が先に確認されます。

次の点に注意してください。

• 確保した金額はその時点で利用額に数えられるため、実際の料金なら上限に収まるリクエストでも、拒否されることがあります。max_tokens を小さくしたチャットのリクエストのように、小さなリクエストは、確保する金額も小さくなります。
• 拒否されたリクエストは課金されず、ジョブも作られません。
• 402 のレスポンスには、Retry-After ヘッダがありません。キーの上限では、error.details.resets_at を読むと、カウンターがいつ数え直されるかが分かります。null のときは、上限がキーの通算の金額なので、より高い上限のキーを使う必要があります。

利用可能な残高が、自分で決めた基準を下回ったときに、webhook のイベント balance.low を受け取れます。基準は、ダッシュボードの設定で指定します。Webhookを参照してください。

MCP サーバーには、同じデータを読み取るツール get_balance があります。MCP サーバーを参照してください。

同じコードは GET /v1/key も返します。すべてのコードは、エラーを参照してください。