Tutoriale
Gemini-4 Argon e Carbon su HiAPI: curl, Python e richieste funzionanti
Una guida pratica all'integrazione per sviluppatori che scelgono tra gemini-4-argon, gemini-4-carbon e gemini-4-carbon@vertex
In questa pagina
Scegli la variante di Gemini-4 prima di scrivere codice
La prima decisione di qualsiasi integrazione con Gemini-4 non è curl o Python, ma quale model ID invii. Su HiAPI, gemini-4-argon, gemini-4-carbon e gemini-4-carbon@vertex sono tre diversi target instradabili, e la stringa che passi nel campo model determina quale backend serve la tua richiesta. Sceglierlo in anticipo ti risparmia il fastidio di fare debug di un corpo di richiesta che non avrebbe mai potuto funzionare.
I tre target in pratica
gemini-4-argon— una variante autonoma di Gemini-4 con il proprio model ID. Trattalo come un modello a sé, non come un alias: il suo comportamento, le caratteristiche di latenza e le proprietà dell'output possono differire da Carbon.gemini-4-carbon— il target Carbon predefinito sotto il routing standard di HiAPI.gemini-4-carbon@vertex— la stessa famiglia Carbon, ma servita tramite un routing supportato da Vertex. Il suffisso@vertexfa parte del model ID stesso, non è un parametro separato.
Come decidere
Parti dal carico di lavoro. Se stai valutando Gemini-4 in modo ampio, esegui lo stesso prompt su gemini-4-argon e gemini-4-carbon e confronta gli output prima di decidere. Se hai effettivamente bisogno del routing Vertex — ad esempio perché corrisponde all'ambiente che il tuo team già gestisce — punta direttamente a gemini-4-carbon@vertex.
In pratica: tutti e tre usano la stessa struttura di richiesta. Scegliere la variante è questione di cambiare una riga, quindi puoi rimandare la decisione finale finché non hai una richiesta funzionante. Se vuoi prima vedere la model card, consulta gemini-4-argon e gemini-4-carbon.
Gli esempi in questa guida usano gemini-4-carbon per tutto il percorso; per seguire qualsiasi variante, basta sostituire quell'ID.
Prepara credenziali e base URL
Prima che qualsiasi corpo di richiesta possa contare, tre cose devono essere corrette: la base URL, la chiave API e il formato dell'header di autenticazione. La maggior parte dei fallimenti alle prime richieste ricade in uno di questi tre punti.
Di cosa hai bisogno
- Una chiave API dalla dashboard del tuo account HiAPI. Trattala come un segreto: caricala da una variabile d'ambiente, non incollarla nei file sorgente.
- La base URL di HiAPI. Tutte le chiamate ai modelli vanno allo stesso host; la variante del modello è selezionata dal campo
model, non dal percorso. - Due header su ogni richiesta:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
Configura il tuo ambiente
export HIAPI_API_KEY="your-key-here"
Poi, prima di scrivere qualsiasi codice, verifica che la tua shell la veda:
echo "${HIAPI_API_KEY:0:4}..."
Se non stampa nulla, la tua chiave non è esportata nella shell corrente e ogni richiesta fallirà con un errore di autenticazione. Risolvilo qui, non nel tuo client.
La struttura di richiesta che userai ripetutamente
Ognuno degli esempi seguenti invia un corpo JSON contenente una stringa model e un array messages. Questa struttura non cambia tra curl e Python, tra non-streaming e streaming, né tra le varianti del modello. Mantienila stabile e potrai portare il codice copiando il corpo della richiesta.
Una richiesta curl funzionante
Ecco una chiamata non-streaming completa e pronta da copiare e incollare. Eseguila prima di aggiungere qualsiasi altra cosa: se questa richiesta passa, hai la prova che chiave, base URL e header sono corretti.
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."}
]
}'
A cosa serve ogni campo
model— il selettore della variante. Cambialo ingemini-4-argonogemini-4-carbon@vertexe colpirai un target diverso senza altre modifiche.messages— un array ordinato. I ruoli sonosystem,usereassistant. Se usi un messaggio di sistema, mettilo per primo.content— il testo del messaggio. Per un semplice turno testuale è una stringa normale.
Leggere il corpo della risposta
La risposta è un oggetto JSON contenente la replica del modello e metadati come l'uso dei token. Poiché è non-streaming, il corpo arriva tutto in una volta e curl esce dopo averlo stampato. Se ottieni un oggetto JSON analizzabile con una replica del messaggio, la tua richiesta funziona: tutto il resto si costruisce su questa base.
Un rapido controllo di sanità: passa l'output attraverso un formattatore JSON (| jq .) così la struttura della risposta è leggibile invece di essere un'unica lunga riga.
Invia la stessa richiesta con Python
La versione Python mantiene il corpo della richiesta identico: cambia solo il trasporto. Usa requests:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
Perché corrisponde esattamente alla chiamata curl
Nota che payload è identico byte per byte al corpo JSON della sezione precedente. Il parametro json= lo serializza e imposta Content-Type per te; il dizionario degli header fornisce l'autenticazione. Modello, messaggi e ruoli sono invariati.
Due abitudini da mantenere
- Imposta un timeout. Senza timeout, una connessione bloccata lascia il tuo processo appeso all'infinito. Per le chiamate non-streaming,
timeout=60è un punto di partenza ragionevole. - Chiama
raise_for_status()prima di leggere il corpo della risposta. Le richieste fallite restituiscono un oggetto di errore strutturato, non un completamento: chiamarejson()su un 4xx ti fuorvia. Lascia prima che l'eccezione si propaghi, poi registra il testo della risposta.
Metti il corpo della richiesta in una funzione o in un piccolo oggetto di configurazione, così le sezioni su streaming e tool calling lo estendono invece di copiarlo.
Aggiungi lo streaming alle chiamate
Prima fai funzionare la richiesta non-streaming. Poi abilita lo streaming: le modalità di fallimento sono diverse, e sovrapporre i due cambiamenti rende gli errori difficili da distinguere.
Abilitare lo streaming
Aggiungi un campo al corpo della richiesta esistente:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "List three uses for a message queue."}
]
}
È tutto ciò che cambia nel protocollo. Il server ora restituisce una serie di eventi invece di un documento JSON.
Consumare correttamente lo stream
Regola chiave: non chiamare .json() su una risposta in streaming. Otterrai un errore di parsing, perché il corpo non è un singolo oggetto JSON. Con requests, itera riga per riga e analizza ogni chunk separatamente:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "List three uses for a message queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
A cosa fare attenzione
- Passa
stream=Truearequests. Altrimenti il client bufferizza l'intero corpo della risposta e vedrai una riga solo alla fine, il che vanifica lo scopo. - Salta righe vuote e messaggi keep-alive non JSON. Il
try/exceptqui sopra è intenzionale: lo stream può contenere righe che non si analizzano come chunk. - Accumula il testo tra i chunk. Ogni chunk trasporta un frammento, non la replica completa. Aggiungi i delta di testo man mano che arrivano.
Quando lo streaming funziona, riporta stream a false nei tuoi test non-streaming, così il tool calling rimane facile da leggere. Per una panoramica del target Carbon, la pagina del modello gemini-4-carbon è un buon punto di riferimento.
Aggiungi il tool calling al corpo della richiesta
Il tool calling cambia la richiesta in due punti: dichiari i tool e gestisci un turno di risposta che può contenere una richiesta di invocazione di un tool invece che testo. Aggiungi questa funzionalità solo dopo che le chiamate testuali non-streaming funzionano.
Dichiarare i tool
Accanto a model e messages, aggiungi un array tools. Ogni tool ha un nome, una descrizione e uno schema JSON per i suoi parametri. La descrizione è importante: è ciò su cui il modello si basa per decidere se invocare quel tool.
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
}
Il ciclo di tool calling
Una richiesta che usa tool è una conversazione, non una singola chiamata:
- Invia il messaggio dell'utente e la dichiarazione dei tool.
- Controlla il turno dell'assistente. Se contiene parametri di invocazione di un tool, il modello vuole che tu esegua qualcosa.
- Esegui la funzione locale: HiAPI non esegue il tuo codice.
- Aggiungi due messaggi: il turno di tool calling dell'assistente e un messaggio con ruolo
toolcontenente il risultato della funzione, collegato all'ID della chiamata corrispondente. - Reinvia la cronologia completa dei messaggi. Il modello ora produce la risposta finale.
Punti di fallimento specifici dei tool
- Schema non corrispondente. Se il tuo schema
parameterscontrassegna un campo come obbligatorio ma il risultato lo omette, i turni successivi potrebbero essere rifiutati. Mantieni lo schema preciso. - Cronologia scartata. Ogni reinvio deve includere il messaggio originale dell'utente e il turno di tool calling, non solo il risultato del tool.
- Streaming più tool. I parametri di invocazione dei tool possono arrivare spezzati su più chunk dello stream. Mentre impari il flusso, esegui i tool con
stream: false, così ogni turno arriva come un oggetto leggibile.
Cambia modello e provider senza riscrivere il client
Poiché la variante del modello è solo una stringa nel corpo della richiesta, cambiare target è una modifica di configurazione, non un refactoring. Progetta il client in modo che legga il model ID da una variabile: variabile d'ambiente, file di configurazione, flag CLI; non codificarlo mai a mano in più punti.
Il cambio in sé
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
Nel codice, fai riferimento a quella variabile nel corpo della richiesta:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
Il suffisso @vertex viene passato insieme alla stringa del modello. Non separarlo in un campo a sé né rimuoverlo: fa parte dell'ID instradabile, e rimuoverlo ti instrada silenziosamente verso il target non Vertex.
Cosa ritestare dopo il cambio
- Turni di solo testo — conferma che l'ID venga riconosciuto e che l'autenticazione sia ancora valida.
- Il tuo prompt reale più lungo — varianti diverse possono gestire input lunghi o strutturati in modo diverso; verifica il troncamento e la formattazione.
- Streaming — riesegui il percorso in streaming, perché il ritmo e i confini dei chunk possono variare tra i target.
- Tool calling — rivalida il ciclo completo di tool calling; il formato dei parametri è dove più spesso emergono le differenze tra varianti.
Mantieni un piccolo script di smoke test che esegua questi quattro controlli sul HIAPI_MODEL attualmente impostato. Così cambiare provider diventa una modifica di configurazione più un comando, non una sessione di debug.
Diagnostica i fallimenti comuni delle richieste
Quasi ogni fallimento di integrazione ricade in poche categorie. Abbina il sintomo, applica la correzione e riesegui la baseline non-streaming prima di cambiare qualsiasi altra cosa.
Autenticazione e routing
- 401 o 403. Chiave mancante, scaduta o con prefisso errato. Verifica che l'header sia esattamente
Authorization: Bearer <key>, con un solo spazio in mezzo, e conferma che la variabile sia effettivamente esportata nella shell o nel processo che esegue il codice. Stampa i primi caratteri per esserne sicuro. - L'endpoint restituisce 404. La tua base URL è sbagliata o un segmento del percorso è duplicato. Il modello va nel corpo della richiesta, non nell'URL.
- Modello non trovato. Errore di battitura nel model ID. Confronta carattere per carattere
gemini-4-argon,gemini-4-carbonegemini-4-carbon@vertex: il suffisso@vertexè quello che più spesso viene dimenticato.
Problemi nel corpo della richiesta
- 400 con un messaggio di schema. Di solito è
messagesmalformato:rolemancante,contentche non è una stringa quando dovrebbe esserlo, o array vuoto. Parti dal corpo minimo di due righe di questa guida e aggiungi un campo alla volta. - 400 dopo aver aggiunto i tool. Il tuo schema
parametersè uno JSON Schema non valido, oppure il turno con il risultato del tool non corrisponde all'ID di chiamata nel messaggio dell'assistente. Registra il corpo completo della risposta: il testo dell'errore indica il campo problematico.
Fallimenti dello streaming
- Errore di parsing JSON sulla risposta. Stai chiamando
.json()su uno stream. Itera invece riga per riga, analizza ogni chunk e salta righe vuote e il marcatore[DONE]. - La risposta arriva tutta in una volta. Hai dimenticato di impostare
stream=Truenella chiamata del client, quindirequestsha bufferizzato l'intero corpo della risposta. - Output troncato. Il tuo ciclo si interrompe in anticipo, di solito su una riga vuota o un messaggio keep-alive. Fermati solo al marcatore esplicito di fine stream.
Disciplina di debug
Biseziona nello stesso ordine in cui hai costruito: autenticazione e header, poi testo non-streaming, poi streaming, poi tool. Ogni livello ha caratteristiche di fallimento diverse, quindi ciò che hai modificato per ultimo è quasi sempre la causa. A ogni fallimento registra lo stato HTTP e il corpo completo della risposta: il messaggio di solito indica il campo specifico.
Fai prima passare la baseline su gemini-4-argon o gemini-4-carbon, poi estendi il corpo della richiesta da lì. Se stai ancora decidendo quale variante sia adatta al tuo carico di lavoro, la pagina del modello gemini-4-argon è il punto da cui iniziare.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business
-
Tutoriale
gemini-4-neon scenari applicativi reali: 5 casi d'uso ad alto valore e punti chiave di integrazione
-
Tutoriale
Tutorial API seedance-2.5-flash image-to-video: curl e Python Requests
Un'esercitazione pratica di integrazione per sviluppatori: struttura della richiesta, input del primo/ultimo fotogramma, polling asincrono e risoluzione degli errori