Tracciatore costi API AI: monitora le spese con gli header
Puoi costruire un tracciatore dei costi API AI in circa cinquanta righe, perché ogni risposta ti indica già il saldo residuo. Questa guida mostra come registrare le spese per richiesta, leggere gli endpoint di saldo e generare un avviso prima che il credito si esaurisca.


Punti chiave
- Ogni risposta contiene un header X-Balance-USD con il tuo credito residuo.
- GET /v1/balance e l'endpoint credit_grants restituiscono il saldo su richiesta.
- Il costo per chiamata è (input x 0,15 + output x 0,50) / 1.000.000 di dollari.
- Registra su CSV, quindi invia un avviso quando il saldo scende sotto una soglia.
Da dove provengono i numeri
Il credito prepagato semplifica il monitoraggio dei costi, perché il fornitore tiene già un totale progressivo. Lo trovi in tre punti:
- L'header di risposta
X-Balance-USDnelle chiamate API, che mostra quanto rimane dopo la richiesta. GET /v1/balance, una semplice ricerca del saldo.GET /v1/dashboard/billing/credit_grants, la rotta in stile OpenAI che strumenti come dashboard e wrapper sanno già come chiamare.
Accanto a questi, ogni completamento restituisce un oggetto usage con i conteggi dei token di prompt e completamento. Combina i token con i prezzi ($0,15 per 1M di input, $0,50 per 1M di output) e puoi calcolare da solo il costo di qualsiasi richiesta, poi confrontalo con la diminuzione del saldo. I due valori dovrebbero coincidere. Se non coincidono, hai trovato qualcosa da indagare. I dettagli completi sui parametri sono nella documentazione.
Leggi l'header in una richiesta
Con curl, aggiungi -i e guarda gli header:
curl -si https://api.uncensoredaiapis.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hi."}]}' \
| grep -i "x-balance-usd"
In Python, l'SDK OpenAI espone le risposte grezze tramite with_raw_response, che ti fornisce gli header e l'oggetto analizzato insieme:
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredaiapis.com/v1", api_key="sk-your-key")
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say hi."}],
)
resp = raw.parse()
print(raw.headers.get("x-balance-usd"), resp.usage.total_tokens)Un piccolo logger che registra ogni chiamata
Avvolgi le tue chiamate in una funzione e scrivi una riga CSV ogni volta. La riga contiene ora, ID della richiesta, conteggi dei token, costo calcolato e saldo.
import csv, time
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredaiapis.com/v1", api_key="sk-your-key")
PRICE_IN, PRICE_OUT = 0.15, 0.50 # dollars per 1M tokens
LOG = "api_spend.csv"
def cost(usage):
return (usage.prompt_tokens * PRICE_IN + usage.completion_tokens * PRICE_OUT) / 1_000_000
def tracked_chat(messages, tag="default"):
raw = client.chat.completions.with_raw_response.create(
model="uncensored", messages=messages)
r = raw.parse()
row = [
time.strftime("%Y-%m-%d %H:%M:%S"),
raw.headers.get("x-request-id"),
tag,
r.usage.prompt_tokens,
r.usage.completion_tokens,
round(cost(r.usage), 6),
raw.headers.get("x-balance-usd"),
]
with open(LOG, "a", newline="") as f:
csv.writer(f).writerow(row)
return r, row
L'argomento tag è il trucco che rende il log utile. Passa un nome di funzione come "summaries" o "chat", e in seguito puoi sommare il costo per tag per vedere quale parte del prodotto consuma il denaro. L'ID della richiesta aiuta se devi mai chiedere riguardo a un addebito o segnalare un problema, poiché identifica la chiamata esatta.
Verifica la correttezza dei calcoli
Prendi una chiamata con 2,400 token di input e 600 token di output:
- Input: 2.400 x 0,15 / 1.000.000 = $0,00036
- Output: 600 x 0,50 / 1.000.000 = $0,00030
- Totale: $0.00066
Mille di quelle costano $0,66. Se il tuo CSV mostra un saldo che scende molto più velocemente della somma dei costi calcolati, controlla i retry che non hai registrato, i job in background che usano la stessa chiave o gli stream che hai lasciato aperti. Le richieste fallite o rifiutate non vengono addebitate, quindi gli errori non dovrebbero modificare il saldo. Confronta i totali su molte chiamate, non su singole, in modo che piccole differenze di arrotondamento si mediino.
Chiamate in streaming e utilizzo
Con stream: true, i numeri di utilizzo arrivano alla fine dello streaming. Raccoglili dall'ultimo blocco, poi registra la riga dopo la chiusura dello streaming.
def tracked_stream(messages, tag="chat"):
usage = None
for chunk in client.chat.completions.create(
model="uncensored", messages=messages, stream=True):
if chunk.choices and chunk.choices[0].delta.content:
yield chunk.choices[0].delta.content
usage = getattr(chunk, "usage", None) or usage
if usage:
with open(LOG, "a", newline="") as f:
csv.writer(f).writerow([time.strftime("%F %T"), "", tag,
usage.prompt_tokens, usage.completion_tokens, round(cost(usage), 6), ""])
Se ti serve solo il saldo, chiama GET /v1/balance dopo che lo stream è terminato. È una richiesta economica e funziona anche come controllo periodico da un job cron.
Somma delle spese per funzionalità
Il CSV è utile solo se lo leggi. Questo breve script somma il costo per tag e mostra l'ultimo saldo, senza pacchetti aggiuntivi.
import csv
from collections import defaultdict
totals, last_balance = defaultdict(float), None
with open("api_spend.csv") as f:
for row in csv.reader(f):
ts, req_id, tag, pin, pout, cost_usd, balance = row
totals[tag] += float(cost_usd)
last_balance = balance or last_balance
for tag, usd in sorted(totals.items(), key=lambda kv: -kv[1]):
print(f"{tag:15s} ${usd:.4f}")
print("latest balance:", last_balance)
Eseguilo quotidianamente e incolla l'output nel canale del team. La spesa che era invisibile diventa un numero di cui le persone possono discutere, e una funzionalità che costa dieci volte le altre spicca immediatamente. Per un budget approssimativo, moltiplica il totale giornaliero per 30 e aggiungi il 20 percento di margine.
Aggiungi un avviso per saldo basso
Restare senza credito a metà giornata porta un prodotto offline, quindi avvisa presto. Un job cron che gira ogni 15 minuti è sufficiente.
import requests
BASE = "https://api.uncensoredaiapis.com/v1"
THRESHOLD = 5.00 # dollars
r = requests.get(BASE + "/balance", headers={"Authorization": "Bearer sk-your-key"}, timeout=10)
print(r.status_code, r.text) # inspect the JSON once to see the field name
# After you know the field name, parse it and compare with THRESHOLD,
# then post to your chat webhook or send an email.
Stampa il JSON grezzo una volta e guardalo prima di scrivere il codice di parsing. Il nome del campo reale richiede dieci secondi per essere verificato, e indovinarlo da un articolo può rompere l'avviso in silenzio. Scegli una soglia che copra almeno un giorno di spesa normale, che il CSV ti dice: somma il costo di ieri e usalo come minimo.
Quando scatta l'allerta, ricarica. Qualsiasi importo intero da $20 a $500 va bene, con +5% di credito da $50, +10% da $100 e +15% da $200, e il credito non scade mai. Per ottenere prima una chiave per il tracker, usa la pagina delle chiavi API.
Abitudini per mantenere prevedibili le spese
- Usa una chiave per ambiente in modo che il traffico di test non si nasconda nei numeri di produzione.
- Limita
max_tokenssugli endpoint dove non servono risposte lunghe. È opzionale per impostazione predefinita, quindi sono possibili risposte illimitate. - Riduci la cronologia delle chat. I token di input sono più economici di quelli di output, ma una lunga cronologia ripetuta ad ogni turno si accumula.
- Rivedi il totale settimanale per tag e cerca il tag che rappresenta più della metà del costo.
Un'abitudine in più: archivia l'ID della richiesta con ogni riga registrata. Se un numero sembra sbagliato un mese dopo, puoi abbinarlo a una chiamata specifica invece di discutere sulle medie. Poiché le richieste fallite non vengono fatturate, i ritentativi per errori non aggiungono costo, ma i ritentativi dopo una risposta riuscita sì, quindi assicurati che la logica di ritentativo si attivi solo per fallimenti reali. Un bug che ritrasmette una richiesta riuscita in un ciclo è la causa più comune di una fattura inaspettata con qualsiasi API a pagamento a consumo.
Altre guide
Domande e risposte
L'header del saldo appare in ogni risposta?
L'header X-Balance-USD fa parte degli header di risposta elencati per questa API. Leggilo dalla risposta grezza e considera un valore mancante come sconosciuto.
Posso ottenere il costo senza registrare ogni richiesta?
Sì. Interroga GET /v1/balance a intervalli regolari e calcola la differenza tra le letture.
Le richieste fallite modificano il saldo?
No. Le richieste fallite o rifiutate non vengono addebitate.
Quale endpoint dovrebbe utilizzare uno strumento della dashboard OpenAI esistente?
Usa l'endpoint GET /v1/dashboard/billing/credit_grants in stile OpenAI, già supportato da molti strumenti.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.