Introduzione
Chat compatibile con OpenAI per Gemini 3 Flash Preview. Una finestra di lettura da 256.000 token, tre livelli di sforzo di ragionamento, 128 schemi di strumenti e output JSON in un’unica chiamata sincrona, con streaming SSE quando lo richiedi.
Gemini 3 Flash Preview è il modello di chat leggero di Google, pubblicato qui come un unico endpoint compatibile con OpenAI. Prezzo unitario basso e primo token veloce ne fanno quello a cui rivolgersi nel roleplay turno per turno e nella narrativa interattiva: legge fino a 256.000 token, risponde con un massimo di 65.536 e offre tre livelli di sforzo di ragionamento, chiamate a strumenti e output JSON.
Caratteristiche principali
La corsia dei turni brevi ad alta frequenza
In una scena che macina centinaia di turni all’ora, quello che si sente è il prezzo unitario e il tempo al primo token, non la capacità di punta del modello. È per questo che sta qui: abbastanza economico perché ogni battuta di ogni giocatore possa passare da un modello, abbastanza veloce perché la conversazione non si fermi mai su una rotellina che gira.
Decidi turno per turno se pensarci due volte
low, medium e high, con medium come valore predefinito. Tieni lo scambio di routine su low per un primo token più rapido e alza a high l’unico turno che deve chiudere un filo narrativo. È una stringa nello stesso corpo della richiesta, quindi cambiarla non costa nulla a livello di integrazione.
Può cambiare sotto i tuoi piedi
Il ciclo di vita di un modello in preview appartiene a Google, e comportamento o disponibilità possono spostarsi senza preavviso. Decidi su quale modello ripiegare prima del giorno in cui questo verrà ritirato.
Parametri della richiesta
| Parametro | Obbligatorio | Nota |
|---|---|---|
messages | Sì | Turni ordinati, dal più vecchio. Il contenuto è una stringa o un array di parti text, |
max_tokens | No | Limita la risposta a 65.536; il valore predefinito è 16.384. Per il gioco turno per turno, da 300 a 800 impedisce al modello di rispondere con un intero capitolo. |
reasoning_effort | No | minimal, low, medium o high; medium è il valore predefinito. I turni di routine girano bene su low, e il turno che deve andare a segno si può alzare a high da solo. |
stop | No | Fino a 4 sequenze, come stringa o come array. La risposta si ferma appena il modello ne scrive una, e il testo corrispondente non viene restituito. almeno 1 caratteri · almeno 1 elementi · al massimo 4 elementi |
seed | No | Qualsiasi intero. |
temperature | No | Da 0 a 2, di serie 1. Google consiglia di lasciare i modelli Gemini 3 a 1,0: sotto quel valore la generazione può entrare in loop o peggiorare. |
top_p | No | Da 0,01 a 1. Regola questo oppure temperature, mai entrambi nello stesso confronto. |
tools | No | Fino a 128 definizioni di funzione per richiesta. al massimo 128 elementi |
tool_choice | No | auto, none, required, oppure un oggetto che nomina una singola funzione. |
response_format | No | Chiedi un oggetto JSON e nomina ogni chiave nel messaggio di sistema: è così che le opzioni a bivi tornano analizzabili. |
Prezzi
Input $0.45 / Output $2.70 per 1 milione di token
Casi d’uso
Roleplay turno per turno
Tieni la scheda personaggio, le regole del mondo e il tono in un unico messaggio di sistema e a ogni turno manda solo la nuova battuta. A centinaia di turni all’ora, il prezzo unitario e il tempo al primo token decidono come si sente la scena molto più di quanto faccia il tetto del modello.
Narrazione e opzioni a bivi
Chiedi il momento successivo più tre scelte, richiedi un oggetto JSON con response_format e nomina ogni chiave nel messaggio di sistema, così la forma delle opzioni resta stabile. Ogni schermata di un’avventura testuale è questa singola chiamata.
Suddividere in fasce una sessione lunga
Manda qui gli scambi di routine e manda a un modello più costoso i turni che contano: una rivelazione, uno scontro, quaranta turni compressi in un paragrafo. Entrambi hanno la forma OpenAI, quindi cambia solo l’id del modello.
Etichettatura di massa e pulizia
Etichettare log di chat, riscrivere riassunti, far rientrare testo libero in campi fissi. Sono lavori in cui è il prezzo per chiamata, non il ragionamento di punta, a decidere se valga la pena farli girare.
Consigli avanzati
Il personaggio nel system, la scena nello user
La scheda personaggio, le regole del mondo e lo stile di narrazione vanno in un unico messaggio di sistema; a ogni turno si aggiungono solo la nuova battuta dell’utente e la risposta dell’assistente. Tenere fermo il messaggio di sistema è ciò che ti permette di capire quale battuta ha cambiato la voce.
Cambia lo sforzo per turno, non per integrazione
Fai girare i botta e risposta di routine su low per un primo token più rapido, poi manda su high il turno che risolve qualcosa. Stesso endpoint, stesso corpo, una stringa diversa.
Limiti da mettere in conto
Il tetto della risposta è 65.536 token e un max_tokens superiore fallisce subito la validazione. Il contenuto dei messaggi è testo, immagini, video e audio. Video e audio caricati possono arrivare a 14 MB in totale per richiesta. Un response_format JSON dà forma alla risposta, ma il parsing e la validazione restano alla tua applicazione. È un modello in preview: Google può modificarlo o ritirarlo, quindi scegli il modello di ripiego prima che questo porti traffico di produzione.
Avvio rapido dell’API
curl --fail-with-body -sN https://api.spicyapi.ai/v1/chat/completions \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"model": "google/gemini-3-flash-preview/chat",
"messages": [
{
"role": "user",
"content": "Summarise the following release notes into three bullet points."
}
],
"stream": true
}' \
| jq --unbuffered -Rrj 'select(startswith("data: ")) | .[6:] | select(. != "[DONE]") | fromjson | if .error then "\n[error] \(.error.message)\n" else (.choices[0].delta.content? // empty) end'
Nel riferimento dell’API trovi autenticazione, schema completo, polling e gestione degli errori.
