Conteggio dei token per i modelli Gemini

I modelli Gemini elaborano input e output in unità chiamate token.

I token possono essere singoli caratteri come z o intere parole come cat. Le parole lunghe sono suddivise in più token. L'insieme di tutti i token utilizzati dal modello è chiamato vocabolario e il processo di suddivisione del testo in token è chiamato tokenizzazione.

Per i modelli Gemini, un token equivale a circa 4 caratteri. 100 token equivalgono a circa 60-80 parole in inglese.

Ogni modello ha un numero massimo di token che può gestire in una richiesta e in una risposta. Conoscere il numero di token del tuo prompt ti consente di sapere se hai superato questo limite. Inoltre, il costo di una richiesta è determinato in parte dal numero di token di input e output, quindi sapere come contarli può essere utile.

Modelli supportati

• gemini-3.1-pro-preview
• gemini-3.8-flash (e le versioni precedenti gemini-3.7-flash, gemini-3.6-flash e gemini-3.5-flash)
• gemini-3.5-flash-lite (e il precedente gemini-3.1-flash-lite)
• gemini-3-pro-image (noto anche come "Nano Banana Pro")
• gemini-3.1-flash-image (ovvero "Nano Banana 2")
• gemini-3.1-flash-lite-image (ovvero "Nano Banana 2 Lite")
• gemini-3.1-flash-tts-preview

I modelli Gemini 2.5 per uso generico e per la generazione di immagini supportano questa funzionalità, ma sono tutti ritirati.

Opzioni per il conteggio dei token

Tutti gli input e gli output per Gemini API vengono tokenizzati, inclusi testo, file di immagini e altre modalità non testuali. Ecco le opzioni per il conteggio dei token:

Controlla il conteggio dei token per le sole richieste (prima di inviarle al modello).

Chiama countTokens con l'input della richiesta prima di inviarla al modello. Viene restituito:

• total_tokens: conteggio dei token di solo input

Controlla il conteggio dei token per richieste e risposte.

Accedi all'attributo usageMetadata nell'oggetto di risposta. Ad esempio:

• prompt_token_count: conteggio dei token solo dell'input
• candidates_token_count: conteggio dei token di output (non include i token di ragionamento)
• thoughts_token_count: conteggio dei token di ragionamento utilizzati per generare la risposta
• total_token_count: conteggio totale dei token per sia l'input che l'output (inclusi i token di ragionamento)

Quando viene trasmesso l'output di streaming, l'attributo usageMetadata viene visualizzato solo nell'ultimo blocco dello stream. È nil per i chunk intermedi.

Tieni presente quanto segue in merito alle opzioni precedenti:

• Non conteggeranno il numero di immagini di input o il numero di secondi nei file di input video o audio. Tuttavia, il conteggio dei token per ciascuna di queste modalità sarà correlato a questi valori.
• Il conteggio dei token di input include il prompt (testo ed eventuali file di input), nonché eventuali istruzioni e strumenti di sistema.
• Il conteggio dei token di output non include i token di ragionamento, che sono forniti in un campo separato.
• Consulta le informazioni aggiuntive specifiche per ogni tipo di richiesta più avanti in questa pagina.
• I modelli Gemini Live API non supportano countTokens. Inoltre, Firebase AI Logic non supporta ancora l'attributo usageMetadata nella risposta dei modelli Live API, ma sarà disponibile a breve.

Prezzi per queste opzioni

• Chiamata countTokens: non è previsto alcun costo per la chiamata countTokens (l'API Count Tokens). La quota massima per l'API Count Tokens è di 3000 richieste al minuto (RPM).

• Utilizzo dell'attributo usageMetadata: questo attributo viene sempre restituito come parte della risposta e non comporta alcun token o addebito.

Informazioni aggiuntive

Ecco alcune informazioni aggiuntive quando lavori con tipi specifici di richieste.

Conteggio dei token di input di testo

Nessuna informazione aggiuntiva.

Contare i token multi-turno (chat)

Tieni presente quanto segue per chiamare countTokens quando utilizzi la chat:

• Se chiami countTokens con la cronologia chat, restituisce il conteggio totale dei token di entrambi i ruoli nella chat (total_tokens).
• Per capire quanto sarà grande il tuo prossimo turno di conversazione, devi aggiungerlo alla cronologia quando chiami countTokens.

Contare i token di input multimodale

Tieni presente quanto segue in merito al conteggio dei token con l'input multimodale:

• Se vuoi, puoi chiamare countTokens sul testo e sul file separatamente.
• Per entrambe le opzioni di conteggio dei token, otterrai lo stesso conteggio dei token indipendentemente dal fatto che tu fornisca il file come dati in linea o utilizzando il relativo URL.

File di input immagine

I file di input delle immagini vengono convertiti in token in base alle loro dimensioni:

• Input di immagini con dimensioni entrambe inferiori o uguali a 384 pixel: ogni immagine viene conteggiata come 258 token.
• Input di immagini più grandi in una o entrambe le dimensioni: ogni immagine viene ritagliata e ridimensionata in base alle necessità in riquadri di 768 x 768 pixel, quindi ogni riquadro viene conteggiato come 258 token.

File di input video e audio

I file di input video e audio vengono convertiti in token alle seguenti tariffe fisse:

• Video: 263 token al secondo
• Audio: 32 token al secondo

File di input del documento (ad esempio PDF)

I file di input PDF vengono trattati come immagini, quindi ogni pagina di un PDF viene tokenizzata nello stesso modo di un'immagine.