Crediti e fatturazione

Come le chiamate API consumano crediti, come funzionano trattenuta e addebito finale, preventivi prima dell’esecuzione, saldo, utilizzo e tetti di spesa.

L’API usa gli stessi crediti di popnow.ai. Non c’è un piano API separato, nessun abbonamento e nessun minimo: acquista un pacchetto di crediti quando te ne servono altri, e i crediti gratuiti dell’iscrizione valgono anche qui.

1 credito = 0,01 $ alla tariffa base. I pacchetti più grandi includono crediti bonus, quindi ogni credito ti costa un po’ meno.
I prezzi dipendono dal modello e dalle opzioni: per immagine, per secondo di video o audio, per richiesta o per 1.000 caratteri di sintesi vocale. La pagina di ogni modello li elenca.
Le risposte riportano ogni importo due volte: in crediti interi (credits, maxCredits, availableCredits …) e come stringa in dollari USA (cost, maxCharge, available …). Usa i campi in crediti; le stringhe in dollari servono alla contabilità.

Come viene addebitata un’attività

hold

settlerelease

I crediti vengono trattenuti all'accettazione e chiusi una volta sola: addebitati sul consumo effettivo oppure restituiti per intero.

Trattenuta. Quando createTask accetta un’attività, il prezzo più alto che può raggiungere viene messo da parte sul tuo saldo (estimatedCredits). I crediti trattenuti non si possono spendere due volte, ma non sono ancora addebitati.
Addebito o rilascio. Quando l’attività termina:
- succeeded → paghi quanto ha davvero consumato, arrotondato per eccesso ai crediti interi e mai oltre la trattenuta. Il resto torna sul saldo.
- failed o expired → tutta la trattenuta viene rilasciata. Non paghi nulla.

Il record dell’attività mostra a che punto è: finché settled è false, credits è la trattenuta; quando settled diventa true, credits è l’addebito finale.

Alcuni modelli addebitano una richiesta che il loro produttore ha rifiutato per motivi di contenuto. In quel caso la pagina del modello lo dice; in tutti gli altri casi il fallimento è gratuito.

Situazione	Addebitato?
`createTask` rifiutato (`400`, `402`, `403`, `429`, `50301` …)	No — nessuna attività, nessuna trattenuta
Attività `succeeded`	Sì, l’importo reale, con la trattenuta come tetto
Attività `failed` o `expired`	No, salvo il caso di rifiuto per contenuto indicato sopra
La connessione è caduta dopo l’invio	Non si sa finché non controlli — reinvia con lo stesso `Idempotency-Key` per trovare l’attività
Leggere attività, modelli, saldo o utilizzo	Mai

Chiedi prima il prezzo

POST /api/v1/jobs/quote riceve esattamente il corpo che invieresti a createTask e restituisce il prezzo senza creare nulla né trattenere crediti:

curl -X POST "https://api.popnow.ai/api/v1/jobs/quote" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alibaba/wan-3.0/image-to-video", "input": {"image_url": "https://media.popnow.ai/movie/lighthouse.webp", "resolution": "720p", "duration_seconds": 5}}'

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "q_…",
    "model": "alibaba/wan-3.0/image-to-video",
    "maxCredits": 68,
    "expectedCredits": 68,
    "estimatedCost": "0.68",
    "maxCharge": "0.68",
    "currency": "USD",
    "quantity": "5",
    "unit": "per_second",
    "expiresAt": "2026-10-16T09:25:00Z"
  },
  "request_id": "req_…"
}

maxCredits è il massimo che la richiesta può costare: l’importo che verrà trattenuto. expectedCredits è quanto costa di solito; i due differiscono solo quando l’addebito finale dipende dal risultato, come la durata reale di una clip.

Perché il prezzo non cambi tra quando lo mostri a un utente e quando l’attività parte, passa quoteId ed expectedCredits (il maxCredits mostrato) a createTask entro cinque minuti. Se qualcosa è cambiato, createTask risponde 40901 e non trattiene nulla; richiedi un nuovo preventivo.

Saldo

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

availableCredits è ciò che le nuove attività possono usare, heldCredits ciò che è messo da parte per le attività in corso, e totalCredits la somma dei due (available, held e total riportano gli stessi importi in dollari). Il nome del percorso è storico e non ha nulla a che fare con la chat. Quando il saldo disponibile non copre la trattenuta di una nuova attività, createTask restituisce 40201.

Utilizzo

GET /api/v1/usage?from=2026-10-01&to=2026-10-16 restituisce, per la chiave con cui lo chiami, il numero di attività, quante sono riuscite e quante fallite e quanto sono costate in crediti — in totale (totalCredits), per giorno e per modello. Le date sono in UTC, to è escluso e l’intervallo è di 92 giorni al massimo. Contano solo gli addebiti chiusi, quindi il totale di un giorno può ancora cambiare mentre terminano attività in ritardo. Questo report è limitato a 30 richieste al minuto; per l’intero account usa la pagina di utilizzo della console API.

Tetti di spesa

Ogni chiave può avere un tetto giornaliero, mensile e totale, impostato nella console API e mostrato in crediti. Una richiesta che lo supererebbe restituisce 40202 e non trattiene nulla. I tetti giornalieri si azzerano alle 00:00 UTC, quelli mensili il primo del mese alle 00:00 UTC, quello totale mai. Se non li imposti, le chiavi non hanno tetti.

Acquisto di crediti e rimborsi

I crediti si acquistano sul sito, non tramite l’API. Pacchetti e prezzi sono nella pagina dei prezzi; la politica di rimborso spiega cosa si può rimborsare e quando.