課金 · SpicyAPI ドキュメント

料金と残高は米ドルで表示され、API では estimatedCost、cost、available、held、total を通貨記号なしの 10 進文字列として返します。会計用途では浮動小数点ではなく decimal 型で解析してください。

API

{
  "available": "128.42",
  "held": "0.36",
  "total": "128.78"
}

利用支援金と後払い枠

GET /api/v1/chat/credit の任意項目 funding は、前払資金、利用支援金、承認済みの後払い枠を分けて返します。旧レスポンスに funding がなくてもゼロとは限りません。SDK は client.getBalance()、CLI は spicyapi balance --json を使います。金額は正確な USD 十進文字列、日時は RFC3339 です。

prepaidAvailableUsd は前払分、grantAvailableUsd は現在有効な支援金の合計です。grants には各支援金の availableUsd、heldUsd、spentUsd、status、startsAt、expiresAt、modelSlugs が含まれます。モデル一覧が空なら全モデル対象です。有効期間外や対象外モデルでは使えず、換金もできません。最大100件を返し、残高または予約額のある付与分を優先して、それぞれ新しい順に並べます。grantsHasMore が true なら未表示の記録があります。表示分の合計を全体の残高として扱わないでください。

credit.limitUsd は承認上限であり現金残高ではありません。credit.availableUsd は未使用枠、usedUsd は精算済みの未返済額、heldUsd は予約済み枠です。期限切れ、停止、超過は新規利用を制限しますが、債務は消えません。available が負でも承認済み枠で利用できる場合があります。cashShortfallUsd が正なら外部決済の回収に伴う不足額があり、支援金や後払い枠では補填できません。受理可否はサーバーが判断します。

割引は料金を、支援金と後払い枠は支払元を決めます。失敗や未使用分の解放は元の資金源に戻しますが、期限切れ・取り消し済み支援金を復活させません。変更は管理者の手動承認後に有効になります。支援金や後払い枠についてはサポートへご相談ください。自分で残高を増やす公開 API はありません。台帳の grant_expire は期限切れ、grant_revoke は取り消しを表します。

現在の API キーの利用状況

GET /api/v1/usage は、認証に使った現在の API キーのタスクだけを集計します。from と to は YYYY-MM-DD の UTC 日付で、範囲は [from,to)（開始日を含み終了日を含まない）、最長 92 日です。既定の to は UTC の翌日、from は to の 7 日前です。totalSpend と各 spend は、精算済みの実際の請求額だけを合計した USD の十進文字列で、未精算の hold は含みません。タスクの作成日で集計するため、後日の精算により過去の日付の金額が変わることがあります。残高やキーの残り予算を示す API ではありません。

顧客割引とキャンペーン

全ユーザー向け、または特定アカウント向けに、全モデル・指定モデルの割引を設定できます。期間のない割引は停止まで、期間限定の割引は実際の開始から終了まで適用されます。アカウント専用料金は、そのアカウントでのログインまたは API キーによる見積もりにのみ適用されます。

割引は重複適用されず、利用できる最安料金が自動で選ばれます。通常 $10、公開割引 10%、アカウント割引 20% なら $8 です。終了後の新しい見積もりには、残っている割引または通常料金が適用されます。

カウントダウンは料金の予約ではありません。認証情報と完全な入力を付けて jobs/quote を取得し、割引・料金・入力が変わったら再見積もりしてください。受理済みタスクは受理時の料金で精算され、実行中に割引が終了しても値上がりせず、請求額は予約額を超えません。

割引は API 利用料金に自動で適用されます。チャージ額の割引や入金へのキャッシュバックではありません。日次・月次予算は現在の料金からの試算であり、期間限定割引が予算期間の途中で終了する場合があります。終了日時も確認してください。

課金単位

モデルの pricing[].unit は per_image、per_second、per_request、per_1k_tokens のいずれかです。quantityField と pricing[].variant はカタログから読み、入力フィールドを推測しないでください。

hold、settle、release

createTask で estimatedCost を hold し、succeeded では実使用量で settle します。failed・expired と履歴 canceled は全額 release されますが、新しい受理済み task は取り消せません。task と hold は一つのデータベーストランザクションで作成され、精算は task ごとに一度だけ完了します。

残高と上限

GET /api/v1/chat/credit は available、held、total を返します。残高不足は 40201、キーの日次・月次・累計上限とプラットフォーム日次上限は 40202 です。日次上限は UTC 0 時、月次上限は UTC の毎月 1 日 0 時に区切りが変わります。累計上限はリセットされません。明示した 0 は無制限を意味します。

台帳

台帳は append-only で、topup、bonus、hold、settle、refund、adjust、chargeback を別々の記録として保持します。これらの残高変動は task の input / output の消去対象ではなく、課金履歴で確認できます。

完全なフィールド定義は OpenAPI 3.1 仕様を参照してください。