venice-billing

Venice Billing

アカウント単位の請求と分析情報を取得する読み取り専用エンドポイントです。仕様では usage-analytics に ベータ版 のタグが付いています。スキーマや動作が変更される可能性があります。

エンドポイント	目的
GET /billing/balance	現在の canConsume フラグ、残りの DIEM、獲得クレジット、付与クレジットと USD、エポックの割り当てを取得します。
GET /billing/usage-history	リクエストごとの台帳を、キーセット（カーソル）ページネーションで取得します。JSON または CSV 形式です。
GET /billing/usage-analytics	日付、モデル、API キー別に集計した内訳を取得します。
GET /billing/usage	廃止済みです。 2026-09-16 に終了し、すべてのリクエストに 410 を返します。

稼働中の 3 つのエンドポイントはいずれも、ADMIN キーによる Bearer 認証が必要です。INFERENCE キーでは 401（"Admin API key required"）が返されます。x402 ウォレット認証には対応していません。ウォレット残高を確認する場合は venice-x402 を使用してください。Authorization ヘッダーのないリクエストには 401 ではなく 402 の x402 検出用レスポンス本文が返されます。支払いオプションは無視し、ADMIN Bearer キーを送信してください。無効なキーには 401 が返されます。

GET /billing/usage は廃止されました。 2026-09-16 以降、認証の有無を問わずすべての リクエストに 410 Gone が返され、使用状況データは取得できません。本文の error 文字列に、 代替エンドポイントとパラメーター名の変更が記載されています。また、レスポンスには Deprecation: @1783555200、Sunset: Wed, 16 Sep 2026 00:00:00 GMT、および Link: </api/v1/billing/usage-history>; rel="successor-version", <https://docs.venice.ai/api-reference/endpoint/billing/usage-history>; rel="deprecation"; type="text/html" が含まれます。 このルートには IP ごとに毎分 60 リクエストのレート制限があり、超過すると 429 が返されます。そのメッセージにも 移行先が記載されています。GET /billing/usage-history に移行してください。 page + limit → pageSize + nextCursor、startDate / endDate → startTimestamp / endTimestamp。

通貨／優先順位

各リクエストの請求には、次の順序で選ばれる 1 種類の通貨が使用されます。

1. DIEM — ステーク済みの DIEM に由来します。割り当てはエポック（UTC の日単位）ごとにリセットされます。
2. EARNED_CREDITS — USD 建ての獲得クレジットです。
3. BUNDLED_CREDITS — Venice の有料サブスクリプションプランに含まれる USD 建てのクレジットです。
4. USD — 前払いの法定通貨残高です。

キューに登録されたジョブや画像など、事前に見積もられる料金は、費用全額をまかなえる最初の通貨から差し引かれます。トークン単価のリクエストは実行後に請求され、残高が正の最初の通貨が使われるため、残高がわずかにマイナスになる場合があります。

旧称が DIEM の VCU は、消費可能な通貨ではなくなりました。/billing/usage-history の currency フィルターでは拒否されます。

キーごとの USD 消費上限は、USD、BUNDLED_CREDITS、EARNED_CREDITS をまとめて対象とします。DIEM の上限は DIEM を対象とします（venice-api-keys を参照してください）。

GET /billing/balance

curl https://api.venice.ai/api/v1/billing/balance \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

{
  "canConsume": true,
  "consumptionCurrency": "DIEM",
  "balances": { "diem": 90.5, "usd": 25, "bundledCredits": 10, "earnedCredits": null },
  "diemEpochAllocation": 100
}

• canConsume は、アカウントで使用可能な DIEM、獲得クレジット、付与クレジット、USD の合計が $0.10 以上の場合に true になります。キーごとの上限やアカウントの API ティアは考慮されません。実際の利用可否チェックは各推論リクエストで行われます。これらも含めて確認するには、GET /api_keys/rate_limits の accessPermitted を使用してください。
• consumptionCurrency は、DIEM、EARNED_CREDITS、BUNDLED_CREDITS、USD の順で残高が正の最初の通貨を示します。該当する通貨がない場合は null です。仕様の列挙型には VCU もありますが、返されることはありません。
• balances.diem は、アカウントが DIEM をステークしていない場合は null です。それ以外の場合は、今のエポックで残っている DIEM を示します。
• balances.usd、balances.bundledCredits、balances.earnedCredits は、残高が正でない場合は null です。
• diemEpochAllocation は、現在のエポックにおける DIEM の総量です。balances.diem / diemEpochAllocation で残りの割合を求められます。

GET /billing/usage-history

タイムスタンプの昇順で返される、リクエストごとの台帳です。キーセット（カーソル）ページネーションを使用します。

curl "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-06-01T00:00:00Z&endTimestamp=2026-07-01T00:00:00Z&pageSize=1000&currency=USD" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Accept: application/json"

クエリパラメーター

リクエストは、フィルター付きの最初のページか、パラメーターなしの続きのいずれかです。 フィルターと一緒にcursorを送信すると400になり、不明なパラメーターを送信した場合も同様です。バリデーターは厳格です。

パラメーター	備考
startTimestamp	省略可能です。ISO 8601 UTC 形式で、Zサフィックスが必要です（最大40文字）。下限は含みます。最初のページでのみ指定できます。
endTimestamp	省略可能です。同じ形式です。上限は含みません。startTimestampより後の日時である必要があります。境界を共有する連続した期間を指定すると、履歴を抜けや重複なくたどれます。
currency	省略可能です。USD／DIEM／BUNDLED_CREDITS／EARNED_CREDITS。
pageSize	10～1000の整数です。デフォルトは1000です。
cursor	前回のnextCursorから取得した、不透明な続行トークン（[A-Za-z0-9_-]、最大512文字）です。続行する履歴のフィルターとページサイズを保持するため、単独で送信してください。

有効期限切れ、改ざん済み、または別のユーザーに発行されたカーソルを指定すると、400（"Invalid or expired cursor; restart from the first page"）が返されます。新しい使用状況が記録されてもページの内容は変わりません。結果の合計数は報告されません。

レスポンス（JSON）

{
  "data": [
    {
      "timestamp": "2026-06-15T19:05:10.504Z",
      "sku": "zai-org-glm-5-1-llm-output-mtoken",
      "units": 0.000227,
      "pricePerUnitUsd": 2.8,
      "amount": -0.06356,
      "currency": "DIEM",
      "notes": "API Inference",
      "inferenceDetails": {
        "requestId": "chatcmpl-4007fd29f42b7d3c4107f4345e8d174a",
        "promptTokens": 339,
        "completionTokens": 227,
        "inferenceExecutionTime": 2964
      }
    }
  ],
  "nextCursor": "AZq3fK9tXhIVDm2j4vN8cQwYt1sB6uEoLxRgPzKaJdHfM5nC7yW0K3w"
}

最終ページではnextCursorはnullです。

フィールド

• sku — 請求項目（モデル＋単位の種類＋形式）。
• units — LLMの場合はトークン数（百万単位。例：0.000227＝227トークン）。
• pricePerUnitUsd — 1単位あたりのUSD料金。
• amount — 借方の場合は負の値です。
• currency — USD、DIEM、BUNDLED_CREDITS、またはEARNED_CREDITS。
• inferenceDetails — 推論以外の項目ではnullです。値がある場合、requestIdは元のレスポンスで返されたidです。promptTokens、completionTokens、inferenceExecutionTime（ミリ秒）は、記録されていない場合はそれぞれnullです（LLM以外の使用状況では、トークン数はnullです）。

CSV

Accept: text/csvを送信します。列：timestamp, sku, pricePerUnitUsd, units, amount, currency, notes, inferenceDetails.requestId, inferenceDetails.inferenceExecutionTime, inferenceDetails.promptTokens, inferenceDetails.completionTokens。 Content-Dispositionはattachment; filename=billing-usage-history-<UTC export stamp>.csvです。そのため、履歴をたどる際、各ページは並べ替え可能な一意の名前でダウンロードされます。CSVにはエンベロープがないため、続行トークンはレスポンスヘッダーの**x-next-cursor**に格納されます。最終ページではこのヘッダーはありません。

履歴全体をたどる

let url = `${base}/billing/usage-history?startTimestamp=${start}&endTimestamp=${end}`
for (;;) {
  const page = await fetch(url, { headers }).then(r => r.json())
  handle(page.data)
  if (page.nextCursor === null) break
  url = `${base}/billing/usage-history?cursor=${encodeURIComponent(page.nextCursor)}`
}

GET /billing/usage-analytics

ダッシュボード用の集計サマリーです。ユーザーと期間ごとに10分間キャッシュされます。

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=7d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

クエリパラメーター（いずれかの方法を選択）

• lookback=Nd — ^[1-9]\d*d$に一致する必要があります。デフォルトは7dです。90dを超える値は90日に制限されます（その場合、レスポンスのlookbackは"90d"になります）。
• または startDate=YYYY-MM-DD と endDate=YYYY-MM-DD（UTC日付、両端を含みます）。期間は最大90日で、endDateはstartDateより前の日付にできません。両方を送信してください。片方だけが指定された場合は無視され、lookbackが適用されます。

レスポンス（選択したキー）

{
  "lookback": "7d",
  "byDate": [{ "date": "2026-04-20", "USD": 0.5, "DIEM": 10.25 }],
  "byModel": [
    {
      "modelName": "GLM 5.1",
      "unitType": "tokens",
      "modelType": "LLM",
      "totalUsd": 0.4,
      "totalDiem": 12.5,
      "totalUnits": 50000,
      "breakdown": [
        { "type": "Output", "usd": 0.3, "diem": 10, "units": 35000 },
        { "type": "Input",  "usd": 0.1, "diem": 2.5, "units": 15000 }
      ]
    }
  ],
  "byModelDaily": [{ "date": 1705276800000, "GLM 5.1": 5.5, "Kimi K2.6": 3.2 }],
  "byModelDailyUsd": [{ "date": 1705276800000, "GLM 5.1": 0.4, "Kimi K2.6": 0 }],
  "topModels": ["GLM 5.1", "Kimi K2.6"],
  "byKey": [
    { "apiKeyId": "key_abc123", "description": "Production Key",
      "totalUsd": 0.8, "totalDiem": 15, "totalUnits": 75000 },
    { "apiKeyId": null, "description": "Web App",
      "totalUsd": 0, "totalDiem": 4, "totalUnits": 25000 }
  ],
  "byKeyDaily": [{ "date": 1705276800000, "Production Key": 8.5, "Web App": 2 }],
  "byKeyDailyUsd": [{ "date": 1705276800000, "Production Key": 0.8, "Web App": 0 }],
  "topKeyNames": ["Production Key", "Web App"]
}

• byDateには、期間内の日ごとに1件のエントリーが含まれます（昇順、ゼロ埋め）。USDの合計にはBUNDLED_CREDITSが含まれますが、EARNED_CREDITSは含まれません。獲得クレジットで支払われた利用額は、すべての分析合計から除外されます。
• byModel／byKeyには、すべてのモデルとキーが支出額（USD＋DIEM）の降順で列挙されます。breakdown（Input／Output／Cache Read／Cache Write …）は、モデルに複数のトークン種別がある場合にのみ含まれます。
• byModelDaily／byKeyDailyはグラフの行です。date（Unix ミリ秒）と、USD＋DIEMを合算した各系列のフィールドが含まれます。byModelDailyUsd／byKeyDailyUsdは同じ行ですが、USD（バンドルクレジットを含む）のみの部分が含まれます。この2つの*Usd配列は返されますが、公開済みスキーマにはまだ含まれていません。
• topModels／topKeyNamesはグラフに表示される系列です。支出額の上位50件に加え、51件以上ある場合に限り、それ以降のすべてを合算した末尾の"Other"系列が含まれます。仕様書にはまだ「top 8」と記載されていますが、APIは50件を返します。
• apiKeyId: null／description: "Web App"は、Veniceウェブアプリからの利用を示します。説明がないキーはKey ...<last 6 of id>と表示されます。説明が重複する場合は、系列が衝突しないよう (...<last 6 of id>)というサフィックスが付加されます。
• クレジットの購入額は除外され、集計されるのは引き落とし額のみです。

レシピ

アカウントが空の場合、推論を呼び出す前に中断する

/billing/balanceのcanConsumeは、キーごとの上限とアカウントのAPIティアを無視します。そのため、代わりにGET /api_keys/rate_limitsのaccessPermittedを使って判定してください（これから使用するキーで機能し、INFERENCEキーも含まれます）。

const { data } = await fetch(`${base}/api_keys/rate_limits`, { headers }).then(r => r.json())
if (!data.accessPermitted) throw new Error('Venice balance exhausted — top up before continuing')

月次CSVエクスポート

curl -D headers.txt "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-04-01T00:00:00Z&endTimestamp=2026-05-01T00:00:00Z&pageSize=1000" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Accept: text/csv" \
  -o billing-april-001.csv

headers.txtからx-next-cursorを読み取り、ヘッダーがなくなるまで?cursor=<token>（ほかのパラメーターは指定しない）を付けて再リクエストします。

上位モデルのグラフ

const a = await fetch(`${base}/billing/usage-analytics?lookback=30d`, { headers }).then(r => r.json())
// chart(a.byModelDaily, { series: a.topModels, xField: 'date' })

エラー

コード	意味
400	/billing/usage-history：いずれかのフィルターとともにcursorが送信された場合、不明なパラメーター、不正なタイムスタンプ、10～1000の範囲外のpageSize、endTimestampがstartTimestampより後ではない場合、または無効／期限切れのカーソル。/billing/usage-analytics：不正なlookback／日付、endDateがstartDateより前の場合、または90日を超えるカレンダー期間（90日を超えるlookbackは拒否されず、90日に制限されます）。
401	無効なキー、またはいずれかの課金エンドポイントでADMIN以外のキーが使用された場合。
402	Authorizationヘッダーがまったくない場合 — x402認証チャレンジ。
410	/billing/usage — 常に返されます。提供終了日は2026-09-16です。
429	/billing/usageへのリクエストがIPあたり毎分60回を超えた場合、または一般的なAPIエラー予算に達した場合。
500	内部エラー。
504	/billing/usage-analyticsのクエリがタイムアウトしました — lookbackまたは日付範囲を短くしてください。

注意事項

• usage-analyticsを含め、すべての課金エンドポイントでADMINキーが必要です（以前のドキュメントでは任意のキーが使えるとされていましたが、2026-07-21に変更されました）。
• /billing/usageは呼び出さないでください。データは返されません。410が返された場合は「今すぐ移行」と扱ってください。
• /billing/usage-historyではstartTimestamp／endTimestamp（Z付きの完全なISO日時）とpageSizeを指定します。/billing/usage-analyticsではlookback、または通常のYYYY-MM-DD形式の日付としてstartDate／endDateを指定します。形式を混在させないでください。
• /billing/usage-historyのcurrencyフィルターではVCUは受け付けられません。DIEMを使用してください。
• 推論以外のエントリー（サブスクリプション料金など）では、inferenceDetailsはnullです。
• 1回の推論リクエストが、同じinferenceDetailsを持つ複数の台帳行（入力トークンSKUと出力トークンSKUが別々の場合など）として記録されることがあります。行をまたいでamountを合計する一方、トークン数を合計する前にrequestIdで重複を除外してください。
• 分析エンドポイントは10分間キャッシュされるため、急増がダッシュボードに反映されるまで、その分の遅れが生じます。
• byModelDaily.dateはUnixミリ秒の整数です。byDate.dateは**YYYY-MM-DD形式の文字列**です。
• Veniceウェブアプリからの利用ではapiKeyId: nullになります。照合時にこれを除外しないでください。
• x402（ウォレット）の残高確認には、これらのエンドポイントを使わず、GET /x402/balance/{walletAddress}を使用してください。