Fatturazione

Dollari, non crediti

I prezzi sono espressi in dollari statunitensi: «$0.008 per immagine», «$0.042 per secondo di output». Fondi prepagati, contributi promozionali e linee di credito sono denominati in dollari, ma un limite di credito non è un saldo in denaro.

La scelta di evitare i crediti è intenzionale. Un sistema a crediti introduce una conversione tra «ricarica X, ricevi Y di bonus» e «quanto vale un credito», rendendo difficile calcolare il costo unitario reale. Il prezzo che vedi è quello che paghi.

Come funziona il pagamento, in breve

1. Prima aggiungi fondi. Un nuovo account parte con un saldo di $0 e non è previsto un piano gratuito. Un'attività inviata prima della ricarica viene rifiutata con 40201 e non costa nulla.
2. Quando un'attività viene accettata, il suo costo stimato viene accantonato. È un importo riservato. Il denaro resta tuo, ma non può finanziare contemporaneamente un'altra attività.
3. Se l'attività riesce, paghi l'utilizzo effettivo, senza mai superare l'importo riservato. L'eventuale differenza torna disponibile nel saldo.
4. Le attività fallite o scadute normalmente liberano tutto l'importo riservato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato soltanto quando la pagina del modello dichiara espressamente questa eccezione. Controlla settled e cost per conoscere l'addebito finale.
5. I limiti di spesa impostati su ciascuna chiave API impediscono a uno script fuori controllo di esaurire il saldo.

Il resto della pagina spiega in dettaglio ogni passaggio.

Aggiungere fondi

Aggiungi fondi in Fatturazione nella console: con carta, criptovalute o trasferimento manuale, quando questa opzione è disponibile. Puoi anche attivare la ricarica automatica per evitare che le attività lunghe si fermino quando il saldo si riduce. Il saldo acquistato non scade; il credito promozionale scade alla data indicata in Fatturazione.

Per una guida passo passo alle opzioni di pagamento, ai tempi di accredito e alla ricarica automatica, consulta Configurazione dell'account. Le ricariche generalmente non sono rimborsabili in denaro; la politica sui rimborsi elenca le eccezioni, come un addebito duplicato.

Tre fasi

Ogni attività attraversa gli stessi tre passaggi di fatturazione. Non richiedono alcuna azione da parte tua: li descriviamo per aiutarti a leggere con sicurezza la cronologia del saldo.

Controllare il saldo

Il modo più rapido è la pagina Fatturazione della console: mostra il saldo disponibile, l'importo attualmente riservato e ogni movimento. Da codice, chiama:

GET /api/v1/chat/credit

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

const res = await fetch('https://api.spicyapi.ai/api/v1/chat/credit', {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const body = await res.json();
if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

const balance = body.data;
console.log(balance.funding ?? balance);

import os, requests

res = requests.get(
    "https://api.spicyapi.ai/api/v1/chat/credit",
    headers={"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"},
)
body = res.json()
if body["code"] != 200:
    raise RuntimeError(f'{body["code"]} {body["msg"]}')

balance = body["data"]
print(balance.get("funding", balance))

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": "128.42",
    "held": "0.36",
    "total": "128.78"
  }
}

Quando i fondi idonei per il modello selezionato e per quel momento non coprono la stima, createTask restituisce 40201. Anche la scadenza del credito, l'esaurimento dei limiti e una carenza derivante dal recupero di un pagamento possono influire sull'accettazione. Non sostituire i controlli del server con un controllo sul client del segno di available.

Non è necessario verificare il saldo prima di ogni generazione: l'accettazione delle attività applica già i controlli sul saldo disponibile e sui limiti di spesa.

// Keep the exact decimal string for display
const usd = task.cost;

from decimal import Decimal
usd = Decimal(task["cost"])   # not float()

Limiti di spesa

Un limite di spesa è un tetto all'importo che può essere utilizzato. A un'attività si applicano fino a sei limiti; il primo raggiunto fa rifiutare l'attività con 40202, prima che venga creata o che siano riservati fondi:

I limiti giornalieri ripartono alle 00:00 UTC; quelli mensili seguono il mese di calendario UTC e ripartono il giorno 1. Il limite totale non si azzera mai. Se viene raggiunto il limite della piattaforma, riprova dopo le 00:00 UTC oppure contatta l'assistenza se il problema si ripete.

Una riserva non ancora regolata conta ai fini di tutti i limiti, totali, mensili e giornalieri, fino al regolamento dell'attività, indipendentemente dal giorno o dal mese in cui ricade: il denaro non è ancora stato speso, ma non può essere speso due volte. I limiti dei team sono descritti in Console e team.

I limiti servono a proteggerti. Un ciclo fuori controllo che consuma un importo elevato in poche ore è un incidente comune in questo settore, e si verifica quasi sempre su un account senza limiti impostati.

Registro dei movimenti

La pagina Fatturazione della console elenca tutti i movimenti del saldo con etichette chiare come Ricarica, In sospeso, Addebitato e Restituito. Quando scarichi l'elenco con Esporta CSV, la colonna kind contiene uno di questi codici stabili:

Il credito bonus viene registrato separatamente dal denaro pagato perché un rimborso del pagamento, cioè denaro restituito alla tua carta, copre soltanto l'importo che hai pagato; il bonus non ha valore monetario. Questo è distinto dalle voci refund sopra descritte, che restituiscono al saldo la riserva di un'attività fallita.

Questi movimenti vengono conservati per 10 anni, separatamente dal contenuto delle attività, così restano disponibili per riconciliazioni e contestazioni anche molto dopo la cancellazione dei prompt e dei risultati. Consulta Conservazione dei dati.

Fatture e riepiloghi di utilizzo

Puoi emettere autonomamente due documenti da Fatturazione → Fatture nella console, entrambi scaricabili in PDF:

Inserisci una sola volta i tuoi dati nella parte superiore di Fatturazione → Fatture. Sono obbligatori nome o ragione sociale, prima riga dell'indirizzo, città e paese; il codice fiscale o numero di registrazione tributaria, come VAT o GST, è facoltativo. I dati vengono stampati esattamente come li inserisci: li fornisci tu e noi non ne verifichiamo nessuno, incluso il numero fiscale. Possono essere stampati soltanto caratteri latini, greci e cirillici, quindi per un'azienda giapponese o coreana usa la forma romanizzata registrata del nome. Un documento già emesso mantiene i dati validi al momento della creazione; le modifiche successive si applicano soltanto ai nuovi documenti.

• Ogni ricarica pagata e ogni mese concluso possono essere documentati una volta. Se il documento esiste già, scaricalo invece di emetterne un altro.
• Per correggere dati errati, scegli Riemetti: il vecchio documento viene contrassegnato come annullato e una sostituzione con un nuovo numero copre la stessa voce. Usa Annulla senza sostituire soltanto quando un documento riguarda la ricarica o il mese sbagliati.
• Gli estratti conto, più in basso nella stessa pagina, sono un'altra cosa: una fotografia mensile fissa di tutti i movimenti del saldo, per la tua contabilità. Non sono ricevute né documenti fiscali.

L'imposta è indicata come zero: siamo un fornitore statunitense, non riscuotiamo né versiamo VAT, GST o imposte sulle vendite per tuo conto, e ogni documento include una nota di inversione contabile. Resta quindi a tuo carico contabilizzare le eventuali imposte dovute nel tuo paese. Una fattura emessa non viene mai modificata: viene annullata e riemessa, registrando la motivazione e il documento sostitutivo.

Unità di fatturazione

Ogni modello ha esattamente una unità di fatturazione.

Non devi indovinare il nome: quantityField sull'endpoint del catalogo lo indica per ogni modello; una stringa vuota significa un'unità per chiamata.

Un modello può avere prezzi diversi per livelli differenti. Risoluzione, durata, opzioni audio e contenuti di riferimento possono influire sul preventivo, a seconda dello schema. pricing[].variant identifica un livello del listino; nel corpo della richiesta non esiste un campo variant. Non presumere che quell'etichetta possa sempre essere inviata come resolution, né calcolare ogni modello moltiplicando il prezzo iniziale per la durata. Invia l'input completo a jobs/quote per ottenere la stima esatta e il limite massimo dell'addebito.

Durata fatturata a blocchi interi

La maggior parte dei modelli per_second fattura la durata esatta prodotta. Alcuni usano invece blocchi fissi: la durata misurata viene arrotondata per eccesso al blocco intero successivo prima di calcolare il prezzo. Con un blocco di 8 secondi, una clip di 6 secondi e una di 8 costano uguale, mentre una clip di 9 secondi costa due blocchi. Non è il comportamento di tutti i modelli fatturati al secondo: si applica soltanto agli endpoint che lo dichiarano, ciascuno nella propria pagina.

Questi endpoint hanno un'altra caratteristica comune, che rende l'arrotondamento visibile nel preventivo: ricavano la durata da un video fornito da te, invece che da un valore duration_seconds scelto da te. Nessuno sa quindi quanto durerà il risultato prima di leggere la clip. Il loro quantityField è vuoto, perciò l'importo preventivato prima dell'invio rappresenta il caso massimo: la clip più lunga accettata dall'endpoint:

{
  "estimatedCost": "0.96",
  "maxCharge": "0.96",
  "quantity": "32",
  "unit": "per_second"
}

Gli importi sono illustrativi; quantity è qui un tetto in secondi, non una misurazione. L'importo preventivato è quello riservato; l'addebito finale viene calcolato sulla durata arrotondata e non supera mai la riserva. La differenza viene liberata al regolamento dell'attività, come nelle tre fasi descritte sopra.

Ne derivano due aspetti da considerare nella pianificazione:

• Calcola il budget sul preventivo, non sulla tua clip. Fino al regolamento dell'attività, il denaro accantonato corrisponde al tetto e conta ai fini dei limiti di spesa come qualsiasi altra riserva.
• Anche una clip breve costa un blocco intero. Ridurre la durata da 9 a 8 secondi può dimezzare il prezzo di un endpoint con blocchi da 8 secondi; ridurla da 8 a 5 non cambia nulla.

Unità e prezzi esatti sono nella pagina dei prezzi e nella pagina di ciascun modello.

Sconti e promozioni per i clienti

Le offerte possono applicarsi a tutti o a un solo account, su tutti i modelli o soltanto su quelli selezionati. Le offerte continuative restano valide fino alla disattivazione; quelle a tempo si applicano soltanto tra l'inizio e la fine effettivi. I prezzi riservati a un account si applicano quando quell'account accede o richiede un preventivo con la propria chiave API, e non vengono mai pubblicati come prezzo di un altro cliente.

Le offerte non si cumulano. Si applica automaticamente il prezzo più basso a cui hai diritto. Su un addebito standard di $10, un'offerta pubblica del 10% e uno sconto dell'account del 20% producono un prezzo di $8, non un prezzo composto di $7.20. Quando un'offerta termina o viene disattivata, i nuovi preventivi usano la migliore offerta ancora valida per te oppure il prezzo standard se non ne resta nessuna.

Le offerte in homepage, nel catalogo e nelle pagine dei modelli aiutano a confrontare le opzioni. Ottieni la stima effettiva da jobs/quote con la tua identità, il modello e gli input completi. Un conto alla rovescia non riserva un prezzo: aggiorna il preventivo quando cambia un'offerta, un input o un prezzo. Le attività accettate mantengono il prezzo fissato anche se l'offerta termina durante l'esecuzione, e l'addebito finale non può superare l'importo riservato all'accettazione.

Le offerte si applicano automaticamente ai costi di utilizzo dell'API, non all'importo della ricarica, e non prevedono cashback sulle ricariche. Gli esempi di budget giornaliero o mensile proiettano il prezzo corrente; un'offerta a tempo può terminare prima del periodo del budget, quindi controlla anche la sua scadenza.

Fondi promozionali e linee di credito

GET /api/v1/chat/credit mantiene available, held e total e può includere un dettaglio funding. Le risposte meno recenti possono omettere funding; un dato mancante non significa zero. Usa client.getBalance() nell'SDK oppure spicyapi balance --json nella CLI.

• funding.prepaidAvailableUsd contiene i fondi disponibili prepagati o preesistenti senza restrizioni; grantAvailableUsd somma i contributi attualmente attivi. Ogni voce in grants riporta importi assegnati, disponibili, riservati e spesi, stato, inizio, scadenza e modelSlugs. Un elenco di modelli vuoto significa tutti i modelli; altrimenti il contributo finanzia soltanto quelli elencati. L'elenco contiene fino a 100 contributi, dando priorità a quelli con saldo residuo o riservato e poi ordinandoli dal più recente. grantsHasMore segnala ulteriori record. Non sostituire il totale dell'account con il subtotale dell'elenco visibile.
• funding.credit descrive una linea approvata con pagamento differito. limitUsd è il tetto, availableUsd è il credito idoneo non utilizzato, usedUsd è il capitale già contabilizzato e ancora da rimborsare, heldUsd è riservato per le attività accettate ed expiresAt è la scadenza. Il limite di credito non è una ricarica, un contributo o un saldo in denaro. Scadenza, disattivazione o superamento del limite restringono le nuove richieste; il debito esistente resta dovuto.
• I fondi promozionali non possono essere prelevati. Gli sconti determinano il prezzo della richiesta; contributi e credito determinano come viene finanziato quel prezzo. Un contributo non riduce il listino del modello. Si applicano il suo ambito di modelli e la sua validità, e gli importi inutilizzati possono scadere o essere revocati. Attività fallite e riserve inutilizzate restituiscono i fondi alla fonte originaria; questo non riattiva un contributo scaduto o revocato.
• Un funding.cashShortfallUsd positivo indica una carenza derivante dal recupero di un pagamento esterno. Contributi e credito non possono coprirla; le nuove chiamate restano bloccate finché non viene coperta. Un available negativo può invece riflettere l'utilizzo di credito approvato. Non dedurre un rifiuto dal suo segno e non sommarlo direttamente al limite di credito. Il server verifica fonti di finanziamento, idoneità del modello, validità e limiti di spesa per accettare una richiesta.

Gli importi restano stringhe decimali esatte in USD e le date usano RFC3339. Indica il fuso orario quando mostri le date. La pagina di fatturazione della console mostra il dettaglio di fondi e contributi; le modifiche diventano effettive soltanto dopo l'approvazione manuale di un amministratore. Per informazioni su contributi o linee di credito, apri una conversazione in Assistenza nella console oppure scrivi a support@spicyapi.ai. L'API pubblica non offre operazioni di scrittura per aumentare autonomamente la tua disponibilità o assegnare contributi.

Utilizzo della chiave API corrente

Per un grafico della spesa giornaliera e per modello dell'intero account o di un team, usa Fatturazione → Utilizzo nella console. L'endpoint API seguente riporta soltanto i dati della chiave che lo chiama:

curl 'https://api.spicyapi.ai/api/v1/usage?from=2026-09-01&to=2026-09-06' \
  -H "Authorization: Bearer $SPICY_API_KEY"

Le date usano UTC e l'intervallo [from,to), quindi questo esempio include il periodo dal 1 al 5 settembre. Ometti le date per ottenere gli ultimi sette giorni, incluso oggi; l'intervallo massimo è di 92 giorni. I risultati appartengono soltanto alla chiave API corrente. Non esiste un parametro per un'altra chiave o per un report dell'intero account; usa chat/credit per il saldo del portafoglio.

data.totalCalls conta tutte le attività; data.totalSpend include soltanto gli addebiti regolati. days e models raggruppano le stesse attività per data di creazione e modello, con stringhe decimali esatte in USD. Le riserve in attesa sono escluse e un regolamento tardivo può aggiornare date precedenti. La cronologia delle attività nascosta resta inclusa; le date senza chiamate sono omesse. Non sommare i due raggruppamenti.

Usa client.getUsage({ from, to }) nell'SDK oppure spicyapi usage --from 2026-09-01 --to 2026-09-06 nella CLI. Questo endpoint ha un proprio limite di frequenza, più restrittivo: consulta Limiti di frequenza.