Introduzione
Chat compatibile con OpenAI per Gemini 3.7 Flash. Una finestra di lettura da 1.048.576 token, tre livelli di sforzo di ragionamento, 128 schemi di strumento e output JSON in una sola chiamata sincrona, con streaming SSE se lo chiedi.
Gemini 3.7 Flash è il modello Flash ad alta velocità di Google, costruito per il lavoro di codice quotidiano, l'uso di strumenti da parte di agenti e l'esecuzione affidabile di procedure a più passi, e pubblicato qui come un solo endpoint di chat compatibile con OpenAI. Una richiesta legge fino a 1.048.576 token e risponde con un massimo di 65.536, lo sforzo di ragionamento si sposta tra low, medium e high turno per turno, e le chiamate a strumenti e l'output JSON sono scritti alla maniera OpenAI.
Caratteristiche principali
Abbastanza rapido da stare dentro un ciclo
Un agente che pianifica, chiama uno strumento, legge il risultato e decide di nuovo passa quasi tutto il tempo reale ad aspettare il modello. Questa è esattamente la forma di lavoro per cui il modello è stato costruito – codice quotidiano, uso di strumenti ed esecuzione a più passi – quindi il ciclo si chiude in fretta invece di incepparsi a ogni salto.
Tre livelli, decisi turno per turno
low, medium e high, con medium di serie. È una sola stringa nello stesso corpo della richiesta, quindi un passo di routine può girare su low mentre il passo che deve venire giusto va su high. Su questo modello non esiste l'impostazione minimal: la rifiuta l'API di Google, e la rifiuta anche questo endpoint invece di riscriverla in silenzio.
1.048.576 token in una sola richiesta
Un modulo intero con i suoi test, una lunga trascrizione di agente con tutti i risultati degli strumenti ancora agganciati, oppure una serie di documenti letti in un colpo solo. Il tetto conta insieme il prompt di sistema, la cronologia e l'output degli strumenti, quindi il budget appartiene al thread e non all'ultimo messaggio.
Parametri della richiesta
| Parametro | Obbligatorio | Nota |
|---|---|---|
messages | Sì | Turni ordinati, dal più vecchio. Il contenuto è una stringa o un array di parti testo, |
max_tokens | No | Mette un tetto alla risposta a 65.536; di serie vale 16.384. |
reasoning_effort | No | minimal, low, medium o high; medium è il valore di serie. I passi di routine girano bene su low, e il passo che deve venire giusto può essere alzato a high per conto suo. |
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 funzione. |
response_format | No | Chiedi un oggetto JSON e nomina ogni chiave nel messaggio di sistema: è così che i risultati di estrazione tornano analizzabili. |
Prezzi
Input $0.675 / Output $3.375 per 1 milione di token
Casi d’uso
Lavoro di codice quotidiano
Leggere un diff e dire che cosa cambia, scrivere il test che mancava, trasformare uno stack trace in una patch. Sono richieste brevi e frequenti, dove il tempo al primo token decide se lo strumento verrà usato o no.
Cicli di strumenti per agenti
Fino a 128 definizioni di funzione per richiesta, con tool_choice per forzare una chiamata precisa o nessuna. Le chiamate a strumenti tornano nella forma OpenAI, quindi a un runtime di agente esistente serve un id di modello e nient'altro.
Esecuzione a più passi su un thread lungo
Un agente che ha già chiamato sei strumenti porta tutti e sei i risultati nella richiesta successiva. Una finestra da 1.048.576 token è ciò che tiene intatto quel thread invece di imporre un passo di riassunto a metà del lavoro.
Estrazione strutturata su grandi volumi
Chiedi un oggetto JSON con response_format, nomina ogni chiave nel messaggio di sistema. Righe di log in campi, ticket in etichette, testo libero in uno schema: è il prezzo per chiamata a decidere se il lavoro vale la pena.
Consigli avanzati
Lascia spazio al ragionamento prima di mettere un tetto alla risposta
Sullo sforzo medium di serie il modello pensa prima di scrivere, e quel pensiero esce dallo stesso budget di max_tokens della risposta. Un tetto stretto spende il budget in deliberazione e restituisce una stringa vuota. Dai a max_tokens spazio vero – qualche migliaio per una risposta di codice – oppure scendi a low su reasoning_effort quando vuoi una risposta breve e nessuna deliberazione.
Cambia lo sforzo a ogni turno, non a ogni integrazione
Fai girare su low i passi di routine di un ciclo, per un primo token più rapido, poi manda su high il passo che deve venire giusto. Stesso endpoint, stesso corpo, una stringa diversa.
Limiti da mettere in conto
reasoning_effort accetta solo low, medium e high. L'API di Google rifiuta minimal su questo modello, quindi lo rifiuta anche questo endpoint invece di riscriverlo in silenzio in qualcos'altro. Il tetto di risposta è 65.536 token e un max_tokens superiore fallisce direttamente la validazione. Il contenuto dei messaggi è testo, immagini e video; le parti audio vengono rifiutate. Il video viene inviato come file caricato, e il video di una richiesta può arrivare a 14 MB in totale.
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.7-flash/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.
