API Gemini 3.1 Pro: contesto lungo, strumenti e costi

Hai una bibbia di sceneggiatura da 300 000 token per una stagione di una serie romantica per adulti e una domanda: dove le scene contraddicono le schede dei personaggi? Gemini 3.1 Pro Preview su SpicyAPI può leggere tutto in una sola chiamata, ma la sua tariffa di input raddoppia oltre i 200 000 token e quella di output sale del 50%. Invia una richiesta grande in streaming, così non raggiunge il timeout delle richieste senza streaming.

Gemini 3.1 Pro Preview (google/gemini-3.1-pro-preview/chat) accetta fino a 1 000 000 di token in input, accetta parti di testo e image_url (non parti PDF, video o audio), supporta strumenti e output JSON e risponde con un massimo di 32 768 token. Le tariffe per il contesto lungo scattano quando l'input totale supera i 200 000 token e si applicano all'intera richiesta.

Limiti e tariffe

Le tariffe dipendono dal totale dei token di input: confronta i livelli di fatturazione standard e per contesto lungo.

Lascia la temperatura al valore predefinito. Google lo raccomanda per i modelli Gemini 3 e valori più bassi possono far entrare il modello in un ciclo. Usa invece response_format e il messaggio di sistema per dare forma all'output.

Quanto costa davvero una chiamata

Costo = token di input x tariffa di input + token di output x tariffa di output, con il livello scelto in base all'input totale (i token in cache contano). Gli esempi usano input senza cache e 4 000 token di output in totale:

I token di ragionamento sono fatturati come output e condividono il budget di max_tokens. Con un impegno di ragionamento più alto, lascia margine oltre la risposta visibile che ti serve: un budget di 4 000 token non garantisce 4 000 token di testo visibile.

Un solo token oltre i 200 000 fa quasi raddoppiare la chiamata, quindi eliminare 5 000 token di vecchia corrispondenza da un pacchetto di 203 000 token fa risparmiare circa il 50%.

Tre cose moltiplicano quella cifra:

• Ogni giro di strumenti rinvia il pacchetto. Un ciclo di strumenti di tre giri su un pacchetto da 250 000 token fattura circa $0.90 di input per giro, $2.70 in tutto, prima dell'output.
• I token in cache costano meno, ma qui non sono controllabili. La tariffa in cache ($0.36 oltre la soglia) si applica all'input servito dalla cache. Per esempio, 300 000 token in cache più 5 000 nuovi e 4 000 di output costano circa $0.19, contro $1.16 senza cache. Il campo cachedContent del formato Gemini viene rifiutato su questa route, quindi calcola il budget senza cache e controlla il costo saldato dopo la prima esecuzione.
• Il blocco del saldo usa tutto il tuo max_tokens. Prima che una richiesta di testo venga eseguita, la piattaforma blocca l'input più l'intero max_tokens al prezzo del modello: circa $4.13 per 1 000 000 di token di input e 32 768 di output. Leggi il codice di errore: 40201 indica saldo insufficiente per il blocco; 40202 un tetto di spesa. Per il primo, riduci un budget di output eccessivo; per il secondo, controlla i tetti della chiave e del workspace. Gli URL di immagini pubbliche fanno inoltre sì che il blocco copra l'intero limite di input; le immagini caricate o inline usano invece una quota fissa per le immagini.

Dopo la prima chiamata, leggi l'header di risposta X-Spicy-Task-Id e consulta il task: il suo costo è definitivo quando settled è true. Usalo, insieme all'usage ricevuto in streaming, per calibrare ogni stima successiva.

Conviene inserire tutto il pacchetto?

Invia l'intero pacchetto quando la risposta dipende dalle relazioni tra tutte le parti: un controllo di continuità su una stagione, una domanda su «cosa è cambiato» in un intero insieme di specifiche, una ricerca di conflitti tra sceneggiature e schede dei personaggi. Invia solo una parte quando la domanda riguarda una scena o un personaggio. Una domanda sull'oggetto di scena di Mara nella scena 18 richiede la scheda del personaggio e le scene 12 e 18, non la stagione.

La memoria lunga di un'app di chat può differire da questo endpoint: l'applicazione può recuperare passaggi selezionati o riassumere i turni vecchi, mentre l'API vede solo i messaggi inviati con la richiesta.

Una grande finestra di input non garantisce che ogni dettaglio venga recuperato. Trovare più fatti sparsi è più difficile che individuarne uno, e le bozze più vecchie possono competere con la versione corrente. La soglia di prezzo non è un confine di accuratezza. Per un controllo mirato:

• Dividi una stagione in archi fino a 150 000 token e verifica ciascuno con le stesse schede dei personaggi.
• Metti la domanda e le regole di output per ultime, dopo tutto il materiale, come raccomanda Google per i prompt lunghi.
• Etichetta ogni blocco (SCRIPT_V3 / scene 12) e richiedi che le risposte citino solo le etichette fornite. Poi verifica che ogni etichetta citata esista nel tuo pacchetto.
• Chiedi conflitti e posizioni, non riscritture. Una risposta da 32 768 token non può comunque contenere una stagione riscritta.
• Escludi le bozze superate. Due versioni della scena 12 nello stesso pacchetto sono il modo in cui un vecchio oggetto di scena viene citato come attuale.

La stessa logica di budget, con tariffe diverse, è sviluppata nella guida ai costi di Claude Sonnet 4.6 e nella guida Claude Opus ai documenti lunghi.

Prepara un pacchetto di testo

La route accetta parti di testo e image_url. Per i controlli di continuità su una sceneggiatura scansionata, l'OCR fornisce testo ricercabile ed etichette di scena stabili: correggi i nomi e i numeri di scena danneggiati prima di costruire il pacchetto. Un URL di PDF incollato in un messaggio di testo non viene letto come documento. Esporta la sceneggiatura, le note sui personaggi e la shot list come testo con etichette stabili:

CHARACTERS_V2
Mara: 32, photographer. Keeps a copper thermos with a blue band.
Jon: 35, composer. Owns the red leather case.

SCRIPT_V3 / scene 12
Mara puts the thermos on the railway bench. Jon carries the case.

SCRIPT_V3 / scene 18
Jon offers Mara the thermos.

Quattro caratteri inglesi per token sono una stima approssimativa per una prima selezione, non un modo per calcolare il prezzo di una richiesta al limite: codice, nomi e testo non inglese vengono suddivisi in token in modo diverso. Lascia un ampio margine sotto i 200 000, includi nella stima il prompt di sistema e le definizioni degli strumenti e usa l'usage restituito per confrontare il conteggio reale.

Trasforma il risultato in una modifica di scena

In questo pacchetto, la scena 12 colloca per ultima volta il thermos con Mara, mentre la scena 18 lo dà a Jon senza un passaggio di mano. Una risposta utile individua questo vuoto e offre una scelta:

• Mostrare Jon che lo recupera prima della scena 18 se il momento deve mostrare attenzione.
• Far recuperare il thermos a Mara stessa se la scena deve mantenere la distanza tra i due.

Scegli il momento della relazione, poi chiedi una battuta che lo realizzi. Il resoconto del modello aiuta a individuare il vuoto; è comunque l'autore a decidere che cosa significa l'azione. L'analisi non deve inventare una scena intermedia e citarla come materiale di partenza. Per la bibbia di una serie, lo stesso approccio individua le scene che presuppongono una riconciliazione prima che la sceneggiatura la mostri: chiedi l'ultimo stato della relazione stabilito, la prima scena contraddittoria e la transizione mancante.

Prova prima nel Playground

1. Apri Gemini 3.1 Pro Preview e passa al Playground.
2. Incolla CHARACTERSV2 e le due scene di SCRIPTV3. Chiedi dove il thermos cambia di mano senza un passaggio mostrato.
3. Scegli se lo recupera Jon o Mara, poi chiedi una battuta che stabilisca quel momento.

Invialo in streaming

Imposta SPICY_API_KEY e invia lo stesso pacchetto di scene dalla tua app. Lo streaming evita l'interruzione di circa 100 secondi che l'edge applica alle richieste senza streaming; i dettagli di implementazione sono nella guida alla chat.

INTENT_KEY=$(uuidgen)
curl --fail-with-body -sN --max-time 600 https://api.spicyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $INTENT_KEY" \
  -D reply.headers -o reply.sse \
  -d '{
    "model": "google/gemini-3.1-pro-preview/chat",
    "stream": true,
    "stream_options": {"include_usage": true},
    "reasoning_effort": "low",
    "max_tokens": 4000,
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Return JSON with conflicts and suggested_fixes arrays. Cite only supplied scene labels. Do not invent missing scenes."},
      {"role": "user", "content": "Fictional adults: Mara, 32, and Jon, 35. SCRIPT_V3 / scene 12: Mara leaves her blue-banded copper thermos on the railway bench. Jon carries his red case. SCRIPT_V3 / scene 18: Jon hands Mara the thermos. Identify any missing prop handoff."}
    ]
  }'

Aggiungi uno strumento solo se l'informazione è fuori dal pacchetto

Tieni una ricerca dei personaggi fuori dal prompt quando il record canonico cambia spesso. Dai al modello una funzione ristretta di sola lettura, come get_character, e lascia che sia l'applicazione a restituire quel record. Limita il numero di giri: quattro giri sullo stesso grande pacchetto possono costare quattro letture di input. Per un controllo fisso di due scene, mettere i fatti nel prompt è più semplice e più economico.

Il grounding nativo di Search e Maps di Google è un'integrazione a parte; questa route di chat usa funzioni che esegue la tua applicazione. Le ricette per la chat mostrano il ciclo di strumenti completo.

Lascia che un Agent prepari la chiamata

Per controlli di continuità ripetuti, chiedi al tuo Agent di programmazione di usare lo SpicyAPI Skill: «Leggi google/gemini-3.1-pro-preview/chat, poi adatta l'esempio al mio input; mostrami la richiesta prima di eseguirla». La consultazione con la CLI è spicyapi models get google/gemini-3.1-pro-preview/chat --json; quella con MCP è spicyapi_model_get con model: "google/gemini-3.1-pro-preview/chat". Le chiamate di chat usano un client compatibile o l'API di chat; i comandi per i task multimediali non generano risposte di chat.

Progetti con contenuti per adulti

L'indicizzazione delle sceneggiature, i controlli di continuità e le note di produzione sono un buon campo d'uso. La prosa esplicita è meno affidabile: SpicyAPI non aggiunge alcun filtro ai contenuti su questa route, ma il modello può rifiutare o attenuare una richiesta. Nei nostri test di settembre 2026, il contenuto scritto di livello L3 è stata completata per intero in 1 richiesta su 3 e la scrittura di scene intime in 4 su 9. Nei test sulle scene intime, la cornice di finzione all'interno della richiesta ha completato 3 su 3, un prompt di sistema da solo 1 su 3 e le richieste dirette 0 su 3. Una richiesta di finzione offre a questo flusso di lavoro un punto di partenza migliore rispetto al solo messaggio di sistema, ma scegli un altro modello se la prosa esplicita affidabile è il risultato principale. La recensione di Gemini 3.1 Pro ne riporta i dettagli.

Errori comuni

Usa la pagina del modello per le tariffe attuali e per provare la route nel Playground. È un modello in preview, quindi decidi quale modello subentra se cambia prima che gestisca traffico di produzione.