GET /v1/credits でコードから残高を確認する

· Hyperouter · 読了目安 4 分

リクエストの料金はプリペイド残高から支払われ、残高でまかなえないリクエストは 402 insufficient_credits で拒否されます。その前に残高不足を知りたい場合は、GET /v1/credits で残高を取得できます。他の呼び出しと同じ API キーで認証します。

呼び出し

curl https://api.hyperouter.app/v1/credits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

レスポンスには 3 つのフィールドがあり、いずれも 10 進数の USD 文字列です。

Field意味
balance_usd残高です。
held_usd未完了のリクエストが確保している額です。
available_usd利用可能な残りの額です。

Hyperouter は、リクエストの実行前にかかりうる最大額を確保し、完了後に実際に使われた分を課金して、残りを解放します（課金と制限）。held_usd があるのはそのためで、リクエストの処理中は、残高の一部を使えません。available_usd は残高から確保額を引いた値で、注目すべき数値です。

アカウントの残高です

残高はキーではなくアカウントに属するため、アカウントのどのキーからも同じ数値が見えます。独自のクレジット上限を持つキーは、available_usd が大きくても、その上限で 402 insufficient_credits により拒否されることがあります。

フィールドは浮動小数点数ではなく文字列です。Hyperouter はお金を正確に数えており、文字列にすることで、解析方法をお客様が決めるまで正確さが保たれます。Python では decimal.Decimal でそのまま読み込めます。TypeScript では、数桁の精度が重要でなければ Number(...) に変換してから比較してください。アラートのしきい値であれば問題になりません。

キャッシュ

レスポンスには Cache-Control: private, no-store が付くため、このヘッダーに従うプロキシやクライアントは保持しません。毎回、最新の値を取得してください。

アラートであれば、1 分に 1 回の確認で十分です。残高が動くのは、リクエストが精算されたときと、スタッフがチャージを反映したときだけで、どちらもそれより短い間隔は必要ありません。

残高不足のアラート

cron や、すでにお使いのスケジューラーから実行できる小さなスクリプトです。

import os
import sys
from decimal import Decimal

import requests

THRESHOLD = Decimal("5.00")  # USD; pick your own

res = requests.get(
    "https://api.hyperouter.app/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['HYPEROUTER_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
credits = res.json()

available = Decimal(credits["available_usd"])
if available < THRESHOLD:
    print(f"Hyperouter balance low: {available} USD available", file=sys.stderr)
    sys.exit(1)

ゼロ以外の終了コードは、ほとんどのスケジューラーがすでにメッセージに変換できます。同じ確認を TypeScript で書くと次のとおりです。

const res = await fetch("https://api.hyperouter.app/v1/credits", {
  headers: { Authorization: `Bearer ${process.env.HYPEROUTER_API_KEY}` },
});
if (!res.ok) throw new Error(`credits: HTTP ${res.status}`);

const { available_usd } = await res.json();
if (Number(available_usd) < 5) {
  console.error(`Hyperouter balance low: ${available_usd} USD available`);
  process.exitCode = 1;
}

呼び出し自体が 401 で失敗した場合は、キーがない、形式が正しくない、不明、または無効のいずれかです。認証エラーに各ケースを掲載しています。

チャージ

現時点ではチャージは手動です。ダッシュボードで、金額、支払い参照番号、支払いのスクリーンショットを添えてチャージの依頼を作成してください。スタッフが支払いを確認して残高に反映します。チャージごとに、支払額の 5.5%（最低 $0.80）の手数料がかかります。担当者が反映するまでの時間を見込んで、しきい値は余裕をもって高めに設定してください。

次のステップ

関連記事