Vai al contenuto principale
Questo documento spiega come viene determinato il prezzo quando si chiama l’API Ace Data Cloud con X402, e quale relazione ha con il normale prezzo dei Credits (crediti) della piattaforma.

Conclusione principale

X402 non è un sistema di prezzi indipendente. Ogni chiamata API ha già un costo in Credits, che è l’unica fonte di prezzo condivisa da tutti i metodi di fatturazione (detrazione di crediti API Token, saldo dell’account, pagamento on-chain X402). X402 converte semplicemente questo costo in Credits in USDC on-chain a un tasso di cambio fisso:
1 Credit = 0.095215 USDC (ovvero 95215 USDC atomic, USDC ha 6 cifre decimali)
In altre parole:
Questo tasso di cambio non è impostato arbitrariamente, equivale al prezzo unitario dei Credits del livello migliore (grandi volumi) della piattaforma. Pertanto, pagare con X402 ≈ acquistare Credits al prezzo unitario del livello migliore e poi consumarli, senza sovrapprezzo X402; al contrario, si usufruisce direttamente del prezzo unitario dei Credits più basso, senza necessità di ricarica anticipata né di API Token.

Base di determinazione del prezzo

La conversione viene completata uniformemente dalla piattaforma e l’importo è coerente per tutte le reti supportate (Base, Solana); le diverse reti differiscono solo per il contratto dell’asset e il metodo di firma, il prezzo è lo stesso.

Relazione con il normale prezzo unitario dei Credits

I Credits della piattaforma sono venduti a livelli secondo il principio «maggiore è l’utilizzo, minore è il prezzo unitario». Quando X402 fattura per chiamata, utilizza uniformemente il prezzo unitario del livello migliore: In altre parole, X402 regola ogni chiamata al prezzo unitario dei Credits del livello migliore. Gli utenti che acquistano Credits con ricariche di piccolo importo avranno un prezzo unitario più alto di X402; solo gli utenti che ricaricano grandi importi hanno un prezzo unitario coerente con X402.

Due forme di prezzo: exact e upto

Nella risposta 402 di X402, maxAmountRequired è l’importo che devi firmare. Ha due forme:
  • exact (prezzo fisso): il prezzo può essere determinato prima dell’elaborazione della richiesta (immagini, video, musica, ricerca, pagamento degli ordini). maxAmountRequired = costo in Credits della chiamata × 0.095215, ovvero l’importo da pagare per questa chiamata (coerente con cost.amount nella risposta di successo).
  • upto (misurazione dell’utilizzo successiva): interfacce come il completamento chat, per le quali si scopre quanti token sono stati usati solo al termine della risposta. maxAmountRequired è un limite massimo (convertito in base al limite di crediti impostato per quel modello: Credits massimi × 0.095215), l’importo effettivo viene regolato in base all’utilizzo reale e non supera il limite massimo.
Per i dettagli del protocollo relativi a questi due scheme, vedere schema di fatturazione exact e upto. Di seguito si parla solo dei prezzi.

Prezzi Chat (completamento chat)

Il completamento chat utilizza la misurazione upto: viene fatturato in base all’utilizzo effettivo di token prompt / completion. Il prezzo per milione (1M) di token = costo in Credits del modello per 1M token × 0.095215, completamente coerente con il prezzo unitario USD mostrato nel catalogo pubblico dei modelli della piattaforma (/api/v1/models?with_pricing=true). La tabella seguente riporta i prezzi reali (presi dal catalogo dei modelli, calcolati al tasso di cambio X402), in USD / 1M token: Note:
  • La tabella mostra i prezzi unitari misurati per token; il costo di una richiesta = token di input × prezzo unitario di input + token di output × prezzo unitario di output.
  • Il limite massimo upto è l’importo massimo consentito da firmare per una richiesta di quel modello; non è l’addebito effettivo, la stragrande maggioranza delle richieste è molto al di sotto del limite massimo.
  • Il limite massimo determina solo «quanto può essere addebitato al massimo», il regolamento reale viene calcolato in base all’utilizzo dei token.

Esempio: preventivo e addebito sono coerenti (exact)

Di seguito è riportata una vera chiamata a pagamento effettuata con l’X402Client ufficiale a serp/google (Base exact). Dimostra la coerenza tra i tre elementi: il preventivo 402, l’importo firmato e il cost restituito nella risposta di successo.
L’cost.amount restituito dalla risposta (0.000952 USDC) è pienamente coerente con la quotazione 402 e con Credits × 0.095215. Il campo settlement è lo stato di regolamento di questo pagamento (authorized = autorizzato); il regolamento on-chain viene gestito dalla piattaforma, per il meccanismo vedi gli schemi di fatturazione exact e upto.

Calcolo della quotazione upto (chat)

La chat è misurata in token. La quotazione di una richiesta (non il limite massimo) viene calcolata con la seguente formula (prendendo gpt-4o-mini come esempio):
Una richiesta di 500 token prompt + 200 token completion:
Il client firma secondo il limite upto (per gpt-4o-mini, 1 Credit = 95215 atomic), che rappresenta soltanto quanto al massimo potrebbe essere addebitato; la quotazione effettiva della richiesta (nell’esempio sopra circa $0.0001) è molto inferiore al limite massimo e viene regolata in base all’utilizzo dei token. Per il meccanismo di regolamento on-chain di upto, vedi gli schemi di fatturazione exact e upto.

Prezzi di altri servizi (exact a prezzo fisso)

Per interfacce come immagini, video, musica e ricerca, il prezzo può essere determinato al momento della richiesta e viene usato exact. La tabella seguente mostra i prezzi effettivi, ricavati dal 402 maxAmountRequired restituito dalle interfacce online per richieste non pagate (la richiesta di una quotazione non comporta addebiti): Note:
  • Il prezzo dello stesso servizio varia in base a modello, risoluzione, durata e azione (soprattutto per i video). La tabella sopra riporta valori effettivi per un determinato insieme di parametri, solo come riferimento di ordine di grandezza.
  • Per queste interfacce a prezzo fisso (exact), il maxAmountRequired nella risposta 402 della richiesta corrisponde all’importo dovuto per quella chiamata (coincide con il cost.amount della risposta riuscita, come già verificato nella sezione precedente).
  • Ogni prezzo viene ottenuto arrotondando per difetto Credits × 0.095215 all’unità atomic (vedi il riferimento di prezzo sopra) e utilizza la stessa conversione della chat. A causa della rappresentazione in virgola mobile e dell’arrotondamento, alcuni valori possono differire di 1 atomic ($0.000001) dal prodotto semplice; fa sempre fede il valore restituito dal 402.

Prezzo di pagamento degli ordini

Quando si pagano ordini della console con X402 (acquisto di piani / ricarica di Credits), il prezzo visualizzato nella pagina dell’ordine fa fede, e l’amount del 402 è la base finale per la firma. Il pagamento degli ordini passa tramite l’API della piattaforma e richiede un token dell’account; per i dettagli vedi il tutorial sul pagamento degli ordini. Un esempio reale nel tutorial sul pagamento degli ordini (acquisto di 10 Credits):
Nota: il pagamento per chiamata (Chat / altri servizi sopra) e il pagamento degli ordini sono due percorsi diversi. Il pagamento per chiamata utilizza uniformemente il prezzo di fascia ottimale di 0.095215/Credit; il pagamento degli ordini segue la tariffazione dei piani, e la differenza tra il prezzo di creazione e l’importo di regolamento finale fa fede al tutorial sul pagamento degli ordini.

Come ottenere i prezzi in tempo reale

I prezzi variano in base al modello e ai parametri; ottienili in tempo reale tramite programma, non codificarli rigidamente:
  • Prezzo per chiamata: invia una richiesta all’API di destinazione senza PAYMENT-SIGNATURE (e senza Authorization), quindi leggi il 402 accepts[].maxAmountRequired restituito. Questo passaggio non comporta addebiti. Per le interfacce exact è il prezzo finale; per le interfacce upto (chat) è il limite massimo, mentre l’importo effettivo viene regolato in base all’utilizzo.
  • Prezzo per token della chat: GET https://platform.acedata.cloud/api/v1/models?with_pricing=true&type=chat, leggi pricing.input_usd / pricing.output_usd per ciascun modello (già calcolati secondo credit_usd_rate).
  • Verifica della conversione: atomic = floor(Credits × 0.095215 × 1e6), USDC = atomic / 1e6 (ovvero USDC ≈ Credits × 0.095215).
Esempio di richiesta minima per ottenere il prezzo:
  • Prezzo X402 = costo in Credits di questa chiamata × 0.095215, è lo stesso prezzo della normale fatturazione in Credits, solo che viene regolato in USDC on-chain.
  • 0.095215/Credit è il prezzo unitario dei Credits del livello migliore (grandi quantità) della piattaforma; per piccole ricariche il prezzo unitario dei Credits è più alto, quindi X402 equivale a ottenere automaticamente il prezzo unitario migliore.
  • Per le API exact (immagini / video / musica / ricerca / ordini), l’importo firmato è l’importo dovuto per questa chiamata; per le API upto (chat), viene firmato il limite massimo e il regolamento avviene in base all’utilizzo effettivo.
  • Il prezzo autorevole è basato su maxAmountRequired restituito da 402: per exact è l’importo dovuto (coincide con cost.amount della risposta di successo, già verificato); per upto è il limite massimo, mentre cost.amount della risposta di successo è l’importo reale regolato in base all’utilizzo (≤ limite massimo).

Documentazione correlata