Grimoire

Ghid pentru Venice Billing

4 min read

Ghid pentru Venice Billing

Ce face

venice-billing este capability-ul pentru verificarea soldului, costurilor și consumului din Venice API. Acoperă trei endpoint-uri read-only, toate marcate Beta:

  • GET /billing/balance — verifică dacă un cont mai poate consuma și întoarce soldurile DIEM/USD disponibile.
  • GET /billing/usage — ledger paginat, per request, disponibil ca JSON sau CSV.
  • GET /billing/usage-analytics — sumar agregat pentru dashboard-uri: pe dată, model și API key.

Îl folosești pentru întrebări de tip: mai există credit, unde s-a dus consumul, ce model costă cel mai mult, ce cheie API a generat trafic, sau cum export consumul pentru reconciliere.

Nu este pentru x402 wallet balance. Pentru x402 folosește capability-ul venice-x402 și endpoint-ul GET /x402/balance/{walletAddress}.

Vezi și All guides pentru restul ghidurilor.

Când îmi folosește

Îți folosește înainte de joburi care pot consuma mult, la audit de costuri, la export lunar, la debugging de request-uri scumpe sau la construirea unui dashboard intern.

Cazuri tipice:

  • verifici canConsume înainte de inference;
  • vezi soldurile DIEM și USD;
  • exporți ledger-ul în CSV;
  • filtrezi usage după monedă, dată, pagină și sortare;
  • identifici top modele după cost sau unități;
  • separi consumul pe API key;
  • cauți un request prin inferenceDetails.requestId.

Ordinea de consum Venice este: DIEM, apoi BUNDLED_CREDITS, apoi USD. VCU există ca legacy/deprecated DIEM și nu ar trebui folosit în cod nou decât pentru compatibilitate.

Atenție: pe /billing/balance, canConsume reflectă doar DIEM pozitiv sau USD pozitiv. Bundled credits pot fi consultate în fluxul real de request, dar nu sunt incluse în acel flag. Dacă faci dashboard, nu transforma canConsume într-un adevăr absolut despre toate sursele posibile de consum.

Cum îl invoc / declanșez

Invocarea exactă depinde de runtime-ul în care este instalat capability-ul. Declanșează venice-billing când taskul cere billing, balance, usage ledger, CSV export sau usage analytics pentru Venice API.

La nivel API, toate endpoint-urile cer Bearer auth:

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

GET /billing/balance și GET /billing/usage cer cheie ADMIN. O cheie INFERENCE primește 401. GET /billing/usage-analytics funcționează cu orice cheie autentificată, dar este scoped la contul din spatele cheii.

Nu pune cheia în documente, loguri, capturi sau commit-uri. Folosește variabile de mediu sau secret store-ul runtime-ului.

Exemplu practic

Vrei un dashboard pentru ultimele zile de consum.

  1. Ceri analytics:
curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_API_KEY"
  1. Folosești câmpurile pregătite pentru grafice:
  • byDate pentru consum pe zile;
  • byModel pentru totaluri pe model;
  • byModelDaily și byModelDailyUsd pentru serii temporale pe model;
  • topModels pentru legendă;
  • byKey, byKeyDaily, byKeyDailyUsd și topKeyNames pentru consum pe chei.
  1. Dacă ai nevoie de audit detaliat, treci la ledger:
curl "https://api.venice.ai/api/v1/billing/usage?limit=500&page=1&sortOrder=desc" \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Accept: application/json"

Pentru CSV, setează Accept: text/csv și paginează cu page=1,2,3,... până când ai trecut de totalPages.

Output / unde aterizează

Output-ul vine direct de la API:

  • /billing/balance întoarce JSON cu canConsume, consumptionCurrency, balances și diemEpochAllocation.
  • /billing/usage întoarce JSON paginat sau CSV. Pentru CSV, serverul setează download ca billing-usage.csv.
  • /billing/usage-analytics întoarce agregări pentru grafice: byDate, byModel, byModelDaily, byModelDailyUsd, byKey, byKeyDaily, byKeyDailyUsd, topModels, topKeyNames.

În ledger, fiecare intrare poate include timestamp, sku, units, pricePerUnitUsd, amount, currency, notes și inferenceDetails. Pentru LLM-uri, units sunt milioane de tokens: 0.000227 înseamnă 227 tokens. amount este negativ pentru debit. inferenceDetails poate fi null pentru SKU-uri non-inference.

Limite / gotchas

  • Endpoint-urile sunt Beta; validează schema înainte să depinzi rigid de câmpuri.
  • /billing/balance și /billing/usage cer cheie ADMIN.
  • usage-analytics este cached aproximativ 10 minute; spike-urile recente pot apărea cu întârziere.
  • lookback acceptă valori până la 90 de zile; valori mai mari pot fi clamp-uite la 90.
  • Pentru intervale calendaristice, startDate și endDate trebuie trimise împreună.
  • Range-urile peste 90 de zile pot întoarce 400.
  • byModelDaily.date este Unix milliseconds; byDate.date este string YYYY-MM-DD.
  • apiKeyId: null înseamnă consum venit din web app, nu eroare.
  • currency poate include USD, DIEM, BUNDLED_CREDITS și legacy VCU.
  • 401 poate însemna auth invalid sau cheie cu rol greșit.
  • 504 pe analytics indică timeout; scurtează lookback sau range-ul.

Graph View