Come usare gemini-omni-1.2-flash tramite l'API HiAPI: curl e Python

Come si presenta una richiesta a gemini-omni-1.2-flash

Prima di scrivere la prima riga di codice, è utile capire di cosa è composta esattamente una chiamata a gemini-omni-1.2-flash su HiAPI. Ogni richiesta che invii è un oggetto JSON, consegnato a un unico endpoint e autenticato con la tua chiave API HiAPI. Questa struttura è coerente tra i modelli, il che significa che, una volta appresa per questo modello, puoi riutilizzare lo stesso schema altrove.

A livello generale, una richiesta contiene quattro tipi di informazioni:

• Identificatore del modello — la stringa gemini-omni-1.2-flash, che indica a HiAPI a quale modello instradare la tua attività.
• Input — il contenuto che desideri che il modello elabori. A seconda della modalità a cui ti rivolgi, si presenta come prompt o come campi di input strutturati.
• Parametri di generazione — opzioni che modellano l'output, come durata e risoluzione. Sono le manopole che regolerai nel seguito di questa guida.
• Metadati della richiesta — qualsiasi informazione necessaria alla piattaforma per identificare e tracciare la tua attività, ad esempio un riferimento lato client utilizzabile per la correlazione.

Struttura della risposta

Anche la risposta è altamente prevedibile. Le chiamate sincrone restituiscono il risultato direttamente nel campo del risultato. Le chiamate asincrone restituiscono invece un handle dell'attività — un identificatore utilizzato per interrogare lo stato e infine ottenere l'output. Stabilire in anticipo quale dei due casi ti riguarda fa risparmiare molto tempo di debug successivo.

Perché la struttura è importante

La maggior parte dei primi fallimenti di integrazione deriva dalla struttura della richiesta: campi mancanti, tipi di parametro errati o l'errata convinzione che la chiamata sia sincrona quando non lo è. Se interiorizzi questa anatomia prima di scrivere codice, gli esempi curl e Python che seguono saranno semplici traduzioni, non formule misteriose.

Un'abitudine utile: conserva il corpo JSON esatto che invii in una variabile o in un file. Quando qualcosa va storto, vuoi vedere cosa è stato effettivamente inviato, non ricostruirlo a memoria.

Autenticazione in una riga

Ogni richiesta porta la tua chiave API nell'header di autorizzazione. Tratta la chiave come un segreto: caricala da una variabile d'ambiente invece di codificarla nel codice e non inserirla mai nel controllo di versione. Questa sola disciplina evita l'errore di sicurezza più comune nelle integrazioni API.

Invia la tua prima richiesta funzionante con curl

Il modo più rapido per verificare che chiave, endpoint e struttura della richiesta siano corretti è una chiamata curl. Elimina ogni livello di astrazione tra te e l'API, quindi se funziona sai che il problema (se esiste) è nel tuo codice, non nella configurazione dell'ambiente.

Passo 1: salva la tua chiave

Metti la chiave API HiAPI in una variabile d'ambiente, così non comparirà nella cronologia della shell o negli script condivisi:

export HIAPI_API_KEY="your_key_here"

Passo 2: costruisci il corpo della richiesta

Scrivi il corpo JSON in un file. Questo mantiene leggibile il comando curl e ti dà un artefatto riutilizzabile:

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "Descrivi il contenuto che vuoi che il modello generi."
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

I valori concreti dei parametri dipendono dal tuo caso d'uso; ciò che conta qui è la struttura. Alla prima chiamata mantieni duration e resolution moderati, così ottieni rapidamente e a basso costo un segnale che la pipeline funziona.

Passo 3: inviala

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Passo 4: leggi la risposta

Se la richiesta è sincrona, vedrai il risultato generato nel corpo della risposta. Se è asincrona, riceverai un handle dell'attività — un ID dell'attività più un campo di stato. Annota questo ID; ti servirà durante il polling.

Se il tuo terminale lo supporta, passa l'output attraverso un formattatore JSON oppure salvalo su file per esaminarlo con attenzione:

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

Passo 5: verifica prima di scalare

Prima che questa chiamata nuda abbia successo e tu sia in grado di leggere l'output, non iniziare a regolare durata, risoluzione o batch. La prima richiesta verde è la tua baseline; tutto il resto sono modifiche incrementali da confrontare con essa.

Portare la chiamata in Python

Una volta che curl funziona, il passaggio a Python è un lavoro meccanico. L'obiettivo è scrivere un piccolo client leggibile che rispecchi esattamente la richiesta, così se la chiamata Python fallisce puoi confrontarla campo per campo con la versione curl.

Un client minimo

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "Descrivi il contenuto che vuoi che il modello generi."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

Aspetti da notare

• json=payload serializza il dizionario per te, ed è per questo che il corpo coincide con il file curl, invece di essere una stringa assemblata a mano.
• raise_for_status() trasforma le risposte non 2xx in eccezioni, così i fallimenti emergono subito, invece di restituire silenziosamente un corpo di errore che poi tenterai di interpretare come risultato.
• timeout=60 impedisce che lo script si blocchi all'infinito quando la connessione si arresta. Scegli un valore in base a quanto prevedi che duri la generazione.

Gestire le due strutture di risposta

Poiché una chiamata può restituire un risultato o un handle dell'attività, ramifica sulla risposta invece di presupporre una sola struttura:

if "job_id" in data:
    print("Attività asincrona avviata:", data["job_id"])
else:
    print("Risultato pronto")

Questo piccolo controllo è la differenza tra un client che funziona in entrambe le modalità e uno che si rompe la prima volta che la piattaforma decide che la tua attività deve essere eseguita in modo asincrono.

Inseriscilo in una funzione

Avvolgi la chiamata in una funzione che accetta prompt, durata e risoluzione come parametri. Così, quando inizi a regolare, eseguire lo stesso codice con parametri diversi diventa banale, e la struttura della richiesta è definita in un solo punto.

Attività asincrone e polling dei risultati

Alcune richieste a gemini-omni-1.2-flash si completano abbastanza rapidamente da restituire il risultato inline. Altre richiedono più tempo e HiAPI restituisce invece un handle dell'attività. La tua integrazione deve gestire entrambi i casi, ed è proprio il percorso asincrono quello in cui crollano i client più fragili.

Riconoscere una risposta asincrona

Una risposta asincrona contiene un identificatore dell'attività e uno stato. Non ottieni l'output completato, ma una promessa: il lavoro è stato accettato e verrà elaborato. Il tuo compito è tornare a controllare.

Polling corretto

L'approccio ingenuo — martellare l'endpoint di stato in un ciclo stretto while True — ha due svantaggi: spreca il tuo budget di rate limit e impone un carico inutile alla piattaforma senza farti ottenere il risultato più in fretta.

Un pattern migliore usa un backoff con intervallo limitato:

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

Tre regole per il polling

• Inizia da intervalli brevi e cresci lentamente. Un intervallo iniziale breve cattura a basso costo le attività rapide; il raddoppio fino a un limite evita che le attività lente vengano controllate troppo spesso.
• Imposta sempre un tempo massimo di attesa. Senza di esso, un'attività bloccata fa restare appeso il tuo processo per sempre. Un timeout che solleva un'eccezione è molto meglio di un blocco silenzioso.
• Distingui successo, fallimento e stato in sospeso. Solo due di questi devono interrompere il ciclo, e solo uno deve restituire un risultato.

Preferisci i webhook quando disponibili

Se hai un carico elevato, il polling di ogni attività non scala bene. Dove HiAPI fornisce callback di completamento, usale per ricevere i risultati invece di chiedere ripetutamente. Per strumenti interattivi e script a basso volume, il polling con backoff è del tutto sufficiente.

In entrambi i casi, tratta l'handle dell'attività come l'identificatore persistente del lavoro. Salvalo, registralo e usalo in seguito per riconciliare i risultati.

Scegliere durata e risoluzione

Durata e risoluzione sono i due parametri che influenzano più direttamente il tuo output — e anche la tua fattura e i tempi di attesa. Nessuno dei due ha un unico valore corretto; la scelta giusta dipende da ciò che stai costruendo. L'importante è sceglierli consapevolmente, non copiare i numeri dagli esempi.

Durata

La durata controlla la lunghezza di esecuzione dell'output generato. Una durata maggiore ti dà più contenuto, ma richiede più potenza di calcolo per la generazione, il che influisce sia sulla latenza sia su come viene fatturata la richiesta (la fatturazione si basa sulla durata dell'output). Alcune indicazioni pratiche:

• Inizia breve durante i test. Una durata ridotta dimostra che la pipeline funziona end-to-end, senza sprecare tempo in ogni iterazione.
• Adatta la durata allo scopo. Una clip breve per anteprime o miniature non richiede la lunghezza di un deliverable completo.
• Non allungare speculativamente. Genera la lunghezza che userai davvero; ritagliare dopo non ti porta alcun vantaggio.

Risoluzione

La risoluzione controlla la fedeltà dell'output. Una risoluzione più alta significa più dettaglio e un payload più grande, con un conseguente aumento di tempi di elaborazione e costi. I compromessi da valutare:

• Anteprime e bozze non richiedono alta risoluzione — sono controlli di correttezza, non il prodotto finale.
• I deliverable finali possono valere un'impostazione più alta, soprattutto se l'output viene mostrato a dimensione piena.
• Banda e archiviazione contano anch'esse: gli output ad alta risoluzione sono più pesanti da trasferire e conservare.

Regola una variabile alla volta

Quando regoli i parametri, cambia un solo elemento alla volta e confrontalo con la chiamata curl di baseline. Modificando contemporaneamente durata e risoluzione, non puoi attribuire a nessuna delle due le variazioni di qualità, latenza o costo. Mantieni una piccola matrice che registra le impostazioni provate e i comportamenti osservati.

Ragiona sul costo come su una formula, non su un numero

Poiché i prezzi si trovano nel pannello dei prezzi del sito, considera il costo come una funzione: il costo totale scala con la durata dell'output e, per risoluzioni più alte, anche con la dimensione dell'output finale e il volume di elaborazione. Il tuo compito è sapere quali parametri guidano quella funzione e poi consultare i prezzi attuali prima di impegnarti su volumi di produzione. Così le tue stime restano corrette anche se i prezzi cambiano.

Errori comuni e come risolverli

La maggior parte dei primi fallimenti di integrazione rientra in poche categorie. Esamina questi punti in ordine — ogni passo dipende dalla correttezza del precedente, quindi saltare controlli ti farà inseguire sintomi superficiali.

1. Struttura della richiesta

Sintomo: errori di validazione, oppure messaggi su campi mancanti o imprevisti.

Soluzione: verifica che il corpo sia JSON valido (le virgole finali sono il colpevole classico), che il campo model sia esattamente gemini-omni-1.2-flash e confronta riga per riga il tuo payload con l'esempio curl funzionante. Se curl funziona e Python no, confronta i due corpi delle richieste.

2. Parametri

Sintomo: un errore che nomina duration o resolution, oppure una dimensione dell'output inattesa.

Soluzione: controlla i tipi (numeri dove servono numeri, stringhe dove servono stringhe) e verifica che i valori siano nell'intervallo accettabile. Se un parametro viene ignorato silenziosamente, assicurati che sia annidato nella posizione attesa dall'API e non a livello superiore.

3. Autenticazione

Sintomo: risposte 401 o 403.

Soluzione: verifica che la chiave sia presente nell'header Authorization con il prefisso Bearer, che la variabile d'ambiente contenga effettivamente un valore (una stringa vuota assomiglia molto a una chiave errata) e che tu non abbia copiato spazi bianchi o virgolette attorno alla chiave. Se sospetti che la chiave sia stata compromessa, rigenerala.

4. Stato dell'attività

Sintomo: esegui il polling ma non vedi mai un successo, oppure tratti un'attività in sospeso come un fallimento.

Soluzione: verifica di interrogare l'ID dell'attività corretto, che il ciclo riconosca tutti gli stati (pending, running, succeeded, failed) e che il tempo massimo di attesa sia abbastanza lungo per un'attività realistica. Registra ogni transizione di stato, così puoi vedere dove si blocca.

5. Rate limit e guasti transitori

Sintomo: risposte 429 o errori 5xx intermittenti.

Soluzione: esegui un nuovo tentativo con backoff e jitter, invece di riprovare immediatamente. Se stai interrogando molte attività, riduci la concorrenza. Gli errori transitori sono normali; un client che riprova in modo intelligente li supera.

Una disciplina di debug

Quando qualcosa va storto, cambia una sola cosa alla volta e riesegui la richiesta più piccola possibile. Conserva i corpi delle risposte originali — i messaggi di errore di solito nominano il campo o la condizione esatti, e leggerli con attenzione fa risparmiare più tempo di qualsiasi congettura.

Checklist per l'integrazione in produzione

Uno script che funziona una volta sul tuo portatile non è un'integrazione. Prima di andare online, colma queste lacune.

Nuovi tentativi con backoff

Avvolgi le chiamate di rete in una strategia di retry che gestisca i guasti transitori — timeout, reset della connessione, risposte 429 e 5xx. Usa un backoff esponenziale con jitter, limita il numero di tentativi e non riprovare mai richieste con errori di validazione; riprovare un corpo malformato non fa che fallire di nuovo più lentamente.

Timeout ovunque

Imposta timeout espliciti per ogni chiamata HTTP. Distingui il timeout di connessione da quello di lettura e assicurati che il timeout delle richieste di generazione sia almeno pari al tempo reale necessario per la generazione — ma con un limite massimo.

Idempotenza attorno alle attività

Un'improvvisa instabilità di rete può verificarsi tra il momento in cui il server ha accettato la tua richiesta e quello in cui ne vedi la risposta. Se riprovi alla cieca, potresti creare attività duplicate. Allega a ogni richiesta logica un riferimento generato dal client, così puoi rilevare e riutilizzare un'attività esistente invece di crearne una nuova, e salva l'handle dell'attività in uno storage persistente con quel riferimento come chiave.

Log che rispondono alle domande

Per ogni richiesta registra il nome del modello, i valori dei parametri (durata, risoluzione), l'handle dell'attività, le transizioni di stato e la latenza. Non registrare mai chiavi API o il contenuto completo dei prompt che potrebbero contenere dati sensibili. Quando qualcosa va storto alle 3 del mattino, questi log sono ciò che ti permette di ricostruire esattamente cosa è successo.

Osservabilità e avvisi

Tieni traccia dei tassi di successo sia delle richieste sia del ciclo di vita delle attività, della distribuzione degli errori per tipo e della latenza end-to-end. Attiva avvisi su tassi di errore persistenti, non su singoli fallimenti. Una dashboard che separa gli errori di validazione da quelli transitori ti dice subito se hai un bug o se la rete non è in buone condizioni.

Igiene della configurazione

Metti endpoint, nomi dei modelli e parametri predefiniti nella configurazione, non sparsi nel codice. Carica le chiavi API da un gestore di segreti o da variabili d'ambiente. Se prezzi e limiti sono rilevanti per la tua pianificazione, consulta il pannello dei prezzi invece di codificare numeri fissi, perché cambiano.

Percorri questa checklist e la tua integrazione con gemini-omni-1.2-flash sarà in grado di gestire traffico reale, non solo il primo test. Inizia da una chiamata curl funzionante, passa a Python e costruisci da lì verso l'esterno.