Endpoint di tokenizzazione e strumenti
In questa pagina
Conta i token prima dell’invio
Prima di ogni chiamata API seria sorgono tre domande: il mio prompt rientra nella finestra di contesto? Quanto costerà? Dove tagliare se il documento è troppo lungo? Rispondere dopo l’invio, quando vedi un errore o ricevi la fattura, costa sempre di più che farlo in anticipo. L’API di Grok offre esattamente lo strumento per questo: un endpoint di tokenizzazione, gratuito e scollegato dal completamento.
L’endpoint /v1/tokenize-text
POST /v1/tokenize-text accetta testo grezzo e restituisce il conteggio corrispondente dei token. La caratteristica chiave si riassume in una frase: a differenza di una chiamata di completamento, questo endpoint non consuma token a pagamento. Conta; non genera.
curl -X POST "https://api.x.ai/v1/tokenize-text" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Your text to tokenize here."
}'
La risposta fornisce il conteggio totale dei token e, a seconda della versione, la scomposizione dei singoli token. Da ciò derivano direttamente tre utilizzi. Primo, la validazione: verifichi che la somma del prompt di sistema, della cronologia e del messaggio utente rimanga entro la finestra del modello target: 1 milione di token su grok-4.3 e 500.000 su grok-4.5. Secondo, la stima dei costi: il numero risultante, moltiplicato per la tariffa del modello, ti dà il prezzo della richiesta prima di impegnarti. Infine, il troncamento: per un documento troppo grande, la tokenizzazione ti mostra dove tagliare nettamente invece di lasciare che l’API rifiuti l’intero contenuto.
Lo strumento visivo della console
Per il prototipaggio, xAI offre un tokenizzatore visivo nella sua console web dove incolli il testo e ne vedi immediatamente la scomposizione. È uno strumento didattico eccellente: usalo almeno una volta prima di progettare i tuoi template di prompt.
Qui farai tre osservazioni utili. Il francese produce significativamente più token dell’inglese per contenuti semanticamente identici, il che impatta direttamente sul costo di un’applicazione in lingua francese. Il codice sorgente viene suddiviso secondo una logica diversa rispetto al testo naturale. E la punteggiatura o i caratteri speciali occupano spesso un token da soli, il che spiega perché JSON verbosi costano sorprendentemente tanto da trasmettere.
Dove inserire il conteggio in una pipeline
Attento al riflesso di tokenizzare sistematicamente prima di ogni chiamata: raddoppi il numero di richieste di rete e aggiungi latenza a ogni interazione, per informazioni che spesso conoscevi già. Riserva il conteggio esatto ai casi in cui l’incertezza è reale.
Per tutto il resto, basta una stima. Conta circa 1,5 token per parola francese, circa 0,3 token per carattere di codice e da 256 a 1.792 token per immagine a seconda delle sue dimensioni. Questi ordini di grandezza, applicati lato client, ti permettono di rifiutare localmente un prompt manifestamente fuori limite senza consumare una chiamata.
Riserva quindi l’endpoint per tre situazioni: prompt le cui dimensioni variano ampiamente, tipicamente documenti forniti dall’utente o estratti recuperati da un sistema RAG; la calibrazione iniziale dei tuoi template, quando stabilisci una volta per tutte il budget di token per ogni blocco costitutivo; e il debug, quando appare un errore di overflow del contesto e devi identificare quale elemento ha causato il gonfiore.
Strumenti integrati, una voce di costo separata
I token non sono l’unica fonte di costo. Gli strumenti API integrati vengono fatturati per chiamata, indipendentemente dal volume di testo scambiato.
| Strumento | Tariffa |
|---|---|
| Web Search | $5 per 1.000 chiamate |
| X Search | $5 per 1.000 chiamate |
| Code Execution | $5 per 1.000 chiamate |
| File Attachments | $10 per 1.000 chiamate |
| Collections Search | $2,50 per 1.000 chiamate |
Fai i calcoli sul tuo traffico prima di generalizzare uno strumento. Un’applicazione che attiva una ricerca web su ogni richiesta paga $5 per mille interazioni solo per lo strumento, cifra che spesso supera il costo dei token consumati nello stesso periodo. La ricerca web non è superflua, ma dovrebbe essere attivata a condizione e non per default.
Punti chiave
- L’endpoint
POST /v1/tokenize-textti permette di contare i token senza addebiti - La console web di tokenizzazione è utile per il prototipaggio e per comprendere il tokenizzatore
- Non chiamare l’endpoint di tokenizzazione su ogni richiesta in produzione: usa le stime
- Gli strumenti integrati (Web Search, Code Execution, ecc.) hanno costi aggiuntivi per chiamata
- Il francese consuma in media circa 1,5 token per parola