Tutoriale
Come chiamare gemini-omni-1.1-flash tramite l'API HiAPI: guida con curl e Python
In questa pagina
Cosa serve prima della prima richiesta
Prima di scrivere qualsiasi codice, verifica quattro cose. Ognuna può farti risparmiare un ciclo di debug.
Una chiave API
Ogni richiesta a HiAPI deve essere autenticata con una chiave API. Generane una nella console del tuo account e assicurati che non finisca nel controllo di versione. Gli esempi seguenti la leggono da una variabile d'ambiente, così la chiave non compare nella cronologia della shell né nei file committati:
export HIAPI_API_KEY="your_key_here"
URL di base e percorso dell'endpoint
L'URL di base è lo stesso per tutti i modelli HiAPI; cambia solo l'identificatore del modello. Il percorso dell'endpoint e il metodo della richiesta vanno presi dalla documentazione di riferimento dell'API, non copiati da un articolo di blog, perché i percorsi sono versionati e possono cambiare. Definisci l'URL di base come costante nel client, così un'eventuale modifica futura richiederà una sola riga.
Identificatore del modello
gemini-omni-1.1-flash viene passato come stringa nel payload della richiesta. Copialo esattamente: i trattini e il suffisso di versione sono importanti. Se lo scrivi male, l'errore è di solito un errore di validazione anziché di routing, il che confonde; vedi la sezione di debug più avanti.
Salva la pagina del modello tra i preferiti
La pagina del modello gemini-omni-1.1-flash è la fonte autorevole per sapere quali parametri esistono, quali valori accettano e com'è strutturata la risposta. Trattala come il riferimento da verificare prima di ogni modifica, non come qualcosa da leggere una volta e basta.
Con queste quattro cose pronte, puoi effettuare la chiamata.
Inviare una richiesta minima con curl
Inizia con la richiesta più piccola possibile. Il suo scopo non è produrre buoni risultati, ma dimostrare che chiave, endpoint e struttura del payload corrispondono. Una volta che funziona, ogni modifica successiva è incrementale.
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Carrellata lenta e costante verso una tazza di ceramica su un tavolo di legno, luce morbida del mattino"
}
}'
Ecco cosa significa ogni parte:
- Metodo e URL — la chiamata è una
POSTverso il percorso dell'endpoint ricavato dalla documentazione di riferimento dell'API, preceduto dal tuo URL di base. - Intestazione
Authorization— trasporta il token bearer. Una variabile mancante o vuota qui è la causa più comune di un 401. - Intestazione
Content-Type— deve essereapplication/json. Senza di essa, il server potrebbe non analizzare affatto il corpo della richiesta. model— la stringa esatta dell'identificatore del modello.input— un oggetto contenente i parametri di generazione. Il prompt va qui; anche risoluzione e durata si aggiungono qui, come descritto di seguito.
Se la chiamata restituisce un identificatore di task o una risposta di stato accettato anziché l'output finale, è normale: la generazione è asincrona. Conserva l'identificatore; servirà per la fase di polling.
Portare la stessa chiamata in Python
La versione Python deve inviare esattamente lo stesso corpo JSON. Mantenere il payload identico rende credibile il porting: se curl funziona e Python no, il problema è nel tuo codice Python, non nella tua comprensione dell'API.
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Carrellata lenta e costante verso una tazza di ceramica su un tavolo di legno, luce morbida del mattino"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
Alcune abitudini da adottare subito:
- Costruisci gli URL con costanti, invece di spargere concatenazioni di stringhe nel codice.
- Imposta timeout espliciti. Senza di essi, una richiesta bloccata può sospendere indefinitamente un worker.
- Chiama
raise_for_status(), così le risposte di errore emergono come eccezioni anziché essere interpretate silenziosamente come corpi di risposta riusciti. - Serializza con
json.dumps, non affidarti alla codifica form, che non produce correttamente l'oggetto annidatoinput.
Una volta che funziona, hai una struttura di richiesta riutilizzabile. Le due sezioni successive aggiungono i parametri che controllano davvero l'output.
Configurare risoluzione e durata nella richiesta
Risoluzione e durata sono campi normali all'interno dell'oggetto input, accanto al prompt. Concettualmente il payload è così:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
Regola chiave: non codificare questi valori a memoria o da un tutorial letto mesi fa. I valori supportati cambiano con gli aggiornamenti del modello, e passare un valore non supportato produce errori di validazione che sembrano errori di payload. Prima di impostarli, verifica sempre i valori attualmente accettati sulla pagina del modello.
Un pattern pratico
Metti i valori nella configurazione, non nel codice:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
Questo porta tre vantaggi. Puoi regolare la qualità dell'output senza cambiare la logica. Puoi eseguire test economici a bassa risoluzione durante lo sviluppo e alzarla solo al rendering finale. Quando la piattaforma aggiunge valori supportati, devi cambiare un solo campo di configurazione invece di scorrere tutto il codebase.
Ci sono altri due tranelli più subdoli da segnalare. Primo, risoluzione e durata sono di solito correlate al costo: la fatturazione tende a essere legata all'output, quindi clip più lunghe e ad alta risoluzione non sono gratuite. Secondo, se un campo è opzionale, omettilo anziché inviare una stringa vuota o null; alcuni validatori rifiutano un null esplicito anche quando il campo stesso è opzionale.
Gestire la generazione asincrona: prima invia, poi esegui il polling
La generazione richiede tempo, quindi l'API adotta il pattern invia-poi-polling. Il tuo client deve trattarli come due operazioni separate con semantiche di retry diverse.
Passo 1: invio
La chiamata di invio è la richiesta che hai già costruito. Restituisce l'identificatore del task — a seconda dell'endpoint, può essere un task ID, un job ID o un campo simile. Analizzalo in modo difensivo:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
Passo 2: polling
Poi usa quell'identificatore per eseguire il polling dell'endpoint di stato finché il task raggiunge uno stato terminale. Un ciclo robusto ha quattro caratteristiche: tempo massimo di attesa, backoff, controllo dello stato terminale e controllo degli errori.
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
Perché questi dettagli contano
- Il backoff esponenziale evita di martellare l'endpoint di stato su un task ancora in coda che richiede un minuto di rendering.
- Una scadenza rigida impedisce che un task bloccato blocchi per sempre un worker. Al timeout registra il task ID per poterlo controllare manualmente.
- Stati terminali espliciti significano che non girerai mai in un ciclo infinito su uno stato imprevisto. Tratta gli stati sconosciuti come "continua ad attendere", ma registralo una volta nei log.
- Policy di retry separate: ripetere la chiamata di invio è più rischioso che ripetere la chiamata di stato, perché può creare task duplicati. Puoi ripetere tranquillamente il polling; ripeti l'invio solo in caso di errori di trasporto espliciti.
Diagnosticare le modalità di errore comuni
La maggior parte dei guasti rientra in poche categorie. Verificale in quest'ordine, perché i sintomi successivi sono spesso causati dai problemi precedenti.
Errori di autenticazione
Sintomo: 401 o 403.
Prima verifica: la chiave esiste davvero nell'ambiente in cui gira il processo? Stampare len(API_KEY) intercetta il classico caso della variabile non impostata che rende vuoto il token bearer. Poi conferma che il formato dell'intestazione sia Bearer <key>, con un solo spazio in mezzo, e che la chiave non sia revocata o limitata a un altro progetto.
Formato del payload errato
Sintomo: 400, con lamentele sul corpo della richiesta o su campi mancanti.
Prima verifica: confronta il corpo della richiesta con la richiesta curl funzionante. Le cause comuni includono l'assenza dell'intestazione Content-Type: application/json, l'invio di dati in codifica form anziché JSON, un oggetto input piatto quando l'API si aspetta l'annidamento (o viceversa), e conversioni di tipo accidentali: una duration numerica inviata come stringa tra virgolette può fallire la validazione.
Valori di parametro non supportati
Sintomo: 400 o 422, che nominano un campo specifico come resolution o duration.
Prima verifica: la pagina del modello, dove sono elencati i valori attualmente supportati. Quasi sempre si tratta di un valore codificato obsoleto, non di un difetto del codice. Se un valore che funzionava prima ora fallisce, supponi prima che il modello sia stato aggiornato e rileggi la documentazione, prima di supporre un guasto del servizio.
Errore di battitura nell'identificatore del modello
Sintomo: errore di validazione o di non trovato, senza menzione del tuo prompt.
Prima verifica: stampa la stringa model e confrontala carattere per carattere con la documentazione. Uno spazio in più alla fine o un numero di versione invertito sono facili da sfuggire.
Timeout e guasti transitori
Sintomo: timeout di connessione, risposte 429 o 5xx. Prima verifica: hai impostato un timeout. Aggiungi i timeout, poi aggiungi retry limitati con backoff solo per 429 e 5xx — non ripetere errori 4xx diversi da 429, perché la richiesta fallirà allo stesso modo ogni volta. Per i task lunghi, ricorda che il risultato finale si ottiene tramite polling; un timeout della chiamata di invio non equivale a un fallimento della generazione.
Tecnicamente valido ma risultato sbagliato
La richiesta riesce ma l'output non è quello atteso. È un problema di prompt, non di API. Rendi il prompt specifico su soggetto, movimento di camera, illuminazione e ritmo, e cambia un solo variabile alla volta per poter attribuire le differenze.
Incapsulare in una funzione client riutilizzabile
L'obiettivo dell'incapsulamento è semplice: la tua logica di business non deve contenere identificatori di modello, nomi di parametri o cicli di polling. Tutti i dettagli legati al modello sono concentrati in un unico punto.
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
Cosa ti offre questo
- Cambiare modello richiede una sola riga. Quando arriva un modello più recente, cambi la costante e i parametri predefiniti; i punti di chiamata non sono interessati.
- I parametri opzionali sono gestiti correttamente. I valori omessi non vengono inviati, evitando il problema di rifiuto del null descritto prima.
- Il polling è invisibile al chiamante. Il chiamante riceve un risultato o un'eccezione, mai un task ID che deve gestire da solo.
- I test diventano facili. Puoi creare stub per
post_jsonewait_for_jobseparatamente, per testare in isolamento la costruzione del payload e la logica di polling.
Organizzazione a livelli
Mantieni la struttura piatta ed esplicita: livello di trasporto (HTTP, intestazioni, timeout, retry), livello del modello (costruzione del payload per gemini-omni-1.1-flash) e livello del task (invio e polling). Una singola funzione generate_video li combina, e ogni livello è abbastanza piccolo da poter essere analizzato facilmente quando qualcosa va storto.
Conferma prima la configurazione della connessione con curl, poi passa a Python per il lavoro vero, leggi la pagina del modello ogni volta che i parametri cambiano, e metti il ciclo di polling dietro un'interfaccia in modo che non si propaghi mai nel codice dell'applicazione.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
kling-image-4.0 scenari applicativi in pratica: 5 utilizzi ad alto valore e punti chiave di integrazione
-
Tutoriale
Come usare qwen-image-2.0-pro tramite l'API HiAPI: curl, Python e una richiesta funzionante
Esercitazione pratica di integrazione per sviluppatori: prima chiamata riuscita, analisi della struttura della richiesta e risoluzione dei problemi
-
Tutoriale
Come chiamare l'API veo-3.1 text-to-video: esempi curl e Python
Guida pratica all'integrazione per sviluppatori