Gemini 4 Argon API: una chat Python con streaming nativo

Una conversazione con l’API di Gemini 4 Argon usa contenuti nativi di Gemini: contents, ruoli e parts. La prima richiesta è piccola. La parte più delicata è conservare correttamente la risposta prima di inviare una domanda successiva. Ricostruire un turno del modello dal solo testo visibile può far perdere contenuti firmati; aggiungere alla cronologia un messaggio di caricamento vuoto può rendere non valida la richiesta seguente.

Questo tutorial usa la libreria standard di Python e l’endpoint nativo di SeedRouter. Tratta la chat testuale e lo streaming. La documentazione API completa descrive l’intera specifica dei parametri; questo articolo segue una richiesta fino a costruire una conversazione utilizzabile.

Prima della prima richiesta

Ti servono Python 3, una chiave API di SeedRouter e un saldo sufficiente sull’account. Conserva la chiave in una variabile d’ambiente chiamata SEEDROUTER_API_KEY; non inserirla nel codice sorgente né in un bundle inviato al browser. Ogni messaggio inviato può comportare costi. L’esempio non ritenta automaticamente le richieste e non effettua chiamate di continuazione.

L’ID del modello è gemini-4-argon e va inserito nel percorso dell’endpoint. Google documenta questo formato nella sua guida alla generazione nativa. SeedRouter usa l’autenticazione Bearer, come mostrato sotto.

Inviare una richiesta all’API di Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

La risposta è una sequenza di eventi inviati dal server, non un singolo documento JSON. Ogni evento data: contiene JSON nativo di Gemini. Il testo visibile si trova in candidates[].content.parts[].text; alcune parti contengono invece ragionamento o firme. usageMetadata può arrivare separatamente dal testo, quindi leggi fino all’ultimo evento prima di considerare completa la risposta.

Questo budget di output volutamente ridotto serve per una prima verifica di funzionamento. Anche il ragionamento consuma il budget, quindi la risposta potrebbe essere incompleta. Aumentalo consapevolmente per i compiti più difficili; non trasformare una risposta incompleta in un ciclo di tentativi invisibile.

Eseguire una conversazione Python di due turni

Scarica l’esempio Python completo, salvalo in locale ed esegui:

python3 gemini-4-argon-chat.py

Chiedi «Explain a mutex in one sentence», poi «Give a Python example of that idea». Lo script aspetta il tuo input prima di ogni richiesta. Inserisci una riga vuota per terminare. La regola fondamentale della cronologia è:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

Lo script scaricabile fornisce anche le impostazioni di generazione, analizza i frame SSE, stampa solo il testo che non è ragionamento e aggiorna la cronologia soltanto dopo un motivo di fine STOP con parts non vuote. Un errore API, un flusso interrotto o una risposta vuota lascia intatta la cronologia precedente. Non reinvia un messaggio senza avvisare.

Il breve frammento sopra spiega la struttura dei dati; esegui il file completo per ottenere tutta la gestione delle richieste. Per una risposta senza streaming, l’operazione corrispondente è generateContent, e gli esempi di riferimento mostrano cURL, Python, Node.js e Go.

Conservare le parts native, non l’indicatore di caricamento

La seconda richiesta deve contenere tre turni reali: il primo messaggio dell’utente, la risposta completata del modello e il secondo messaggio dell’utente. Il testo «Sto pensando…» mostrato nell’interfaccia non è un altro turno del modello.

Un errore come contents.3.parts: Too small: expected array to have >=1 items significa che la quarta voce di contenuto ha un array parts vuoto. L’indice parte da zero. Controlla come viene costruita la cronologia prima di cambiare il prompt o il modello. Un indicatore di caricamento appartiene allo stato di visualizzazione; non deve mai diventare { "role": "model", "parts": [] } nella richiesta.

Conserva ogni parte restituita nell’ordine originale, inclusi thoughtSignature e i contenuti contrassegnati come ragionamento, anche se l’interfaccia li nasconde. La guida alle firme di ragionamento di Google spiega perché questi campi opachi devono essere mantenuti nei turni successivi. Non modificare, inventare o ricostruire una firma. Salva la cronologia nativa separatamente dal testo mostrato nell’interfaccia.

Lo stesso principio di conservazione vale per le conversazioni con strumenti, ma eseguire uno strumento e restituirne il risultato richiede un ciclo applicativo più ampio. Questo esempio testuale non implementa tale ciclo e non va presentato come un agente di programmazione completo.

Leggere il consumo e gestire l’arresto

Per le richieste dirette, conserva gli ultimi valori di utilizzo riportati dal flusso. Non sommare le istantanee cumulative ripetute all’interno della stessa richiesta. L’input ordinario è promptTokenCount meno cachedContentTokenCount; l’output fatturato comprende sia candidatesTokenCount sia thoughtsTokenCount. La guida ai prezzi trasforma questi conteggi in un budget.

Ctrl+C interrompe l’esempio e non invia altre richieste. Interrompere la lettura locale non dimostra che la generazione remota non abbia usato token. Se il flusso termina prima dell’arrivo dei dati di utilizzo, consulta il registro dei consumi dell’account. Per prudenza, l’esempio esclude il turno incompleto dalla cronologia futura; conservare risposte parziali è una decisione applicativa separata.

La decodifica lunga è un altro caso distinto. Un motivo di fine CONTINUATION riprende la generazione originale con un token di continuazione; non è un nuovo messaggio dell’utente. Google richiede la richiesta originale e il token più recente, senza aggiungere l’output parziale a contents. Consulta la guida alla decodifica lunga. Questo script introduttivo si ferma invece di implementare la continuazione automatica.

Che cosa è stato verificato?

Lo streaming di testo di base ha superato una verifica end-to-end locale tramite il Playground di SeedRouter. L’analisi dei dati e la gestione della cronologia dell’esempio vengono controllate con flussi sintetici che comprendono parti firmate, risposte vuote e interruzioni. Questi dati di test servono a verificare il software, non sono ulteriori esecuzioni del modello. Strumenti, contenuti multimediali e continuazione richiedono ancora verifiche separate delle capacità prima di poter essere descritti come integrazioni verificate.

Domande sull’API

Posso sostituire il nome di un modello OpenAI con gemini-4-argon?

Questo, da solo, non converte i formati dei messaggi. La guida usa i campi Gemini nativi contents e parts. Verifica che il client supporti quel protocollo, oltre all’autenticazione e all’endpoint che configuri.

Perché la risposta è vuota anche se sono stati usati token?

Il ragionamento può consumare il budget di output; anche le impostazioni di sicurezza o una generazione incompleta possono impedire la comparsa di testo visibile. Controlla il motivo di fine e il consumo. Non inserire un turno del modello vuoto e non ripetere automaticamente la richiesta a pagamento.

Un contesto da un milione di token significa un milione di token in output?

No. Input, ragionamento e output condividono il contesto. Le generazioni lunghe hanno anche limiti per richiesta e possono richiedere la continuazione. Calcola il budget sul totale condiviso, non su quote di input e output separate.

Aggiungere funzioni dopo aver fatto funzionare la conversazione

Parti da una risposta completa, poi verifica che il secondo turno riceva il contenuto nativo originale. Mantieni separati la cronologia dell’API di Gemini 4 Argon e lo stato di visualizzazione quando aggiungi allegati, strumenti o persistenza. Il Playground del modello e la guida all’accesso sono i passi successivi per l’uso interattivo e i requisiti dell’account.