Consumo e fatturazione

Il consumo per richiesta arriva in ogni risposta: puoi fatturare partendo da lì con fiducia. Un'istantanea del saldo è disponibile con GET /v1/dashboard/balance.

Consumo per richiesta

Ogni risposta di /v1/messages include un oggetto usage con il conteggio dei token:

{
"usage": {
"input_tokens": 48,
"output_tokens": 92,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}

Per chat-completions gli stessi numeri compaiono come prompt_tokens, completion_tokens e total_tokens.

Saldo della chiave: GET /v1/dashboard/balance

Restituisce il saldo attuale della chiave. Risponde all'istante e usa la stessa chiave dell'API.

curl -H "Authorization: Bearer sk-YOUR_KEY_HERE" \
https://api.oneprovider.dev/v1/dashboard/balance

Risposta 200 OK:

{
"object": "balance",
"balance_usd": 54.77,
"expires_at": "2026-07-29T19:00:00Z",
"is_active": true,
"last_synced_at": "2026-06-29T19:52:00Z"
}

• balance_usd: il saldo disponibile della chiave in USD.
• expires_at: la scadenza della chiave (ISO 8601 UTC, null se non c'è).
• is_active: false se la chiave è in pausa o disattivata.
• last_synced_at: quando il saldo è stato aggiornato l'ultima volta.

Endpoint del saldo compatibili con OpenAI

App come NextChat e LobeChat leggono il saldo da percorsi in stile OpenAI. Funzionano con la stessa chiave in Authorization: Bearer:

Errori: 401 per un header Authorization: Bearer mancante o non valido; 429 quando superi il limite di frequenza (gli endpoint del saldo hanno un limite per IP). Saldo e spesa per richiesta sono anche nell'area personale (la pagina «Consumo» nel bot @oneprovider_robot e su app.oneprovider.dev ).

Tariffe effettive

Addebitiamo a prezzo fisso per 1M di token, alla tariffa pubblicata su /pricing . Nessun moltiplicatore, nessun minimo, nessun arrotondamento. Il calcolo è:

cost = (input_tokens / 1_000_000) * rate_in
+ (output_tokens / 1_000_000) * rate_out
+ (cache_read_input_tokens / 1_000_000) * (rate_in * 0.10)
+ (cache_creation_input_tokens / 1_000_000) * (rate_in * 1.25)

• Le letture della cache sono addebitate al 10% della tariffa di input per la maggior parte dei modelli.
• La creazione della cache (la prima volta che viene scritto un punto di cache) è addebitata al 125% della tariffa di input per la maggior parte dei modelli.
• I moltiplicatori 0,10 e 1,25 della formula sono quelli tipici: le tariffe esatte di lettura e scrittura cache di ciascun modello sono nella tabella dei modelli .

Quando il saldo finisce

Quando il saldo della chiave arriva a zero, le richieste con quella chiave restituiscono 429 con error.type insufficient_balance, error.code insufficient_quota e l'header x-should-retry: false:

HTTP/1.1 429 Too Many Requests
x-should-retry: false
Content-Type: application/json
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}

Non riprovare: controlla il saldo dell'area personale e il limite della chiave (la pagina «Chiavi»), ricarica l'area personale se serve e invia di nuovo la richiesta (come ). Tutti gli altri codici sono trattati in Codici di errore .

Rate-limit (429)

Troppe richieste in poco tempo restituiscono 429 rate_limit_error. La risposta può contenere un header Retry-After in secondi:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded; retry later"
}
}

Quando Retry-After è presente, attendi almeno quel tempo; altrimenti riprova con una pausa crescente. Se i 429 continuano, riduci la concorrenza lato client. Le richieste bloccate dal limite di frequenza non consumano saldo.

Precisione del consumo per richiesta

Gli oggetti usage per richiesta, sommati, corrispondono esattamente alla spesa reale per chiave. Verificato il 2026-05-08 su un campione di 24 ore di 25.845 richieste: lo scarto massimo è stato inferiore a $0,001 (arrotondamento alla sesta cifra decimale). Puoi fatturare con fiducia partendo dall'usage di ogni richiesta.