Blog

Tutoriale

Chiamare veo-3.1/image-to-video tramite l'API HiAPI: tutorial curl e Python

Nov 12, 2026
Immagine di copertina: strati di carta bianco osso sfalsati l'uno sull'altro, con un foglio separatore rosso ruggine inserito nel mezzo, ombra dall'andamento lineare.
In questa pagina

Cosa si aspetta l'endpoint veo-3.1 image-to-video

Prima di scrivere la prima riga di codice, è utile capire che tipo di chiamata sia questa. veo-3.1/image-to-video non restituisce il video direttamente nella risposta HTTP in cui invii il prompt. È un'endpoint per attività asincrone: descrivi il video che desideri, la piattaforma accetta l'attività e poi torni a interrogare il risultato.

Concettualmente, una richiesta è composta da due parti ben distinte:

  • Immagine del primo fotogramma. È il fotogramma statico di partenza da cui viene generato il video. Fissa la composizione, il soggetto e l'aspetto del momento iniziale. Tutto ciò che segue viene generato dal modello a partire da questo punto.
  • Opzioni di generazione. Sono i parametri che controllano come viene generato il video, ad esempio se produrre l'audio, la risoluzione di output e la durata della clip.

Questa separazione è importante per due motivi. Primo, rende più semplice ragionare sui guasti: un problema dell'immagine si presenta diversamente da un problema dei parametri, e vuoi poterli distinguere. Secondo, significa che anche il tuo codice dovrebbe essere organizzato allo stesso modo: una parte logica si occupa di preparare l'immagine, un'altra di costruire l'insieme delle opzioni.

Chi effettua la chiamata deve fornire almeno: un'immagine del primo fotogramma valida e le decisioni su audio, risoluzione e durata. Tutto il resto, ovvero invio dell'attività, monitoraggio dello stato e recupero del video finale, è gestito dal ciclo di vita dell'attività della piattaforma. La tua integrazione deve fare solo tre cose: inviare una richiesta nel formato corretto, memorizzare l'identificatore dell'attività restituito ed eseguire polling finché l'attività non raggiunge uno stato terminale.

Un consiglio pratico prima di proseguire: poiché la chiamata è asincrona, il tuo codice non può presupporre che il video sia disponibile subito dopo l'invio. Progetta il flusso tenendo conto di questo fin dall'inizio e il resto del tutorial risulterà naturale.

Il modello mentale in due parti

Mantieni questo schema mentre leggi le sezioni seguenti:

  1. Input → l'immagine del primo fotogramma preparata e validata.
  2. Opzioni → audio, risoluzione, durata.
  3. Attività → invio, ottenimento dell'identificatore, polling, recupero.

Ognuna delle sezioni seguenti corrisponde a uno di questi riquadri.

Preparare l'immagine del primo fotogramma

L'immagine del primo fotogramma è il singolo input più importante in una chiamata image-to-video, quindi dedica alla sua preparazione un passaggio specifico nella pipeline, invece di nasconderla nel costruttore della richiesta. La chiamata API deve poter fare riferimento a quell'immagine, il che significa che l'immagine deve essere in una forma accettata e leggibile dalla piattaforma.

Cosa verificare prima dell'invio

  • L'immagine si apre davvero. Download troncati o file corrotti sono la causa più comune di errori poco chiari a valle. Prima di inviare qualsiasi cosa, verifica che l'immagine si decodifichi correttamente.
  • Il formato è accettato dalla piattaforma. Se la tua fonte è uno screenshot, una foto da smartphone o un'esportazione da uno strumento di design, normalizzala in un formato ampiamente supportato prima del caricamento. Convertire una volta in anticipo è più semplice che fare debugging dopo.
  • Le dimensioni sono ragionevoli. Immagini minuscole o estremamente allungate offrono al modello materiale insufficiente. Se la fonte è troppo piccola, valuta un ingrandimento o scegli un fotogramma migliore.
  • La composizione è un buon punto di partenza. Poiché questo è il primo fotogramma, il movimento generato proseguirà da lì. Scegli un fotogramma in cui il soggetto sia chiaramente visibile e la cui composizione ti soddisfi come inizio della clip.

Mantenerla separata dalle opzioni

Organizza il codice in modo che la preparazione dell'immagine restituisca un riferimento da passare al costruttore della richiesta, invece di mescolare elaborate dell'immagine e assemblaggio dei parametri. In concreto:

# Struttura pseudocodice, non un client completo
def prepare_first_frame(path):
    image = load_and_validate(path)   # decodifica, controlla formato, controlla dimensioni
    ref = upload_or_encode(image)     # genera qualcosa a cui la chiamata API possa fare riferimento
    return ref

def build_request(first_frame_ref, options):
    return {
        "first_frame": first_frame_ref,
        # audio / risoluzione / durata vanno qui
    }

Questa separazione ripaga durante il debugging. Se l'attività fallisce, puoi rieseguire prepare_first_frame da solo per confermare che il lato immagine sia integro prima di toccare qualsiasi parametro di generazione.

Validare presto, fallire in modo esplicito

Esegui la validazione dalla tua parte e lancia errori chiari in caso di fallimento. Un'immagine in formato errato o illeggibile non dovrebbe mai raggiungere la rete: intercettarla in locale trasforma un vago fallimento di un'attività asincrona in un'eccezione precisa e immediata scritta da te.

Impostare le opzioni di generazione: audio, risoluzione e durata

Una volta gestita l'immagine, le decisioni rimanenti riguardano le opzioni di generazione. Esse cambiano la natura dell'output, quindi trattale come parametri denominati espliciti, non come valori magici sepolti nel corpo della richiesta.

Audio

L'opzione audio controlla se il video generato include una traccia audio. È sia una decisione tecnica sia una decisione di prodotto:

  • Se il video verrà incorporato in modalità silenziosa, ad esempio loop di sfondo o visual principale in autoplay, di solito l'audio non serve e ometterlo semplifica l'elaborazione a valle.
  • Se la clip deve essere presentata autonomamente con il suono, ad esempio contenuti brevi per i social o demo, abilita l'audio così una singola chiamata produce il materiale completo.

Decidi consapevolmente in base al caso d'uso, invece di adottare ciecamente il valore predefinito; influisce sia sull'output sia su come la tua pipeline a valle gestisce il file.

Risoluzione

La risoluzione determina le dimensioni in pixel del video finale. Scegli in base a dove verrà mostrato il video e a quanto dettaglio serve, non semplicemente scegliendo "il valore massimo disponibile". Una clip destinata a un piccolo player incorporato non trae beneficio dall'essere generata a dimensioni molto superiori a quelle del pannello di visualizzazione. Se la piattaforma pubblica un insieme di valori supportati, scegli esplicitamente tra quelli e valida di conseguenza nel client, così i valori non supportati falliscono rapidamente.

Durata

La durata stabilisce la lunghezza della clip generata. Interagisce con la pianificazione dei contenuti: un'inquadratura che deve prima stabilire la scena e poi mostrare il movimento richiede più tempo di un singolo gesto. Tieni presente che questo è uno dei parametri più probabilmente misurati: la fatturazione della piattaforma è descritta in termini di output generato, quindi quando invii richieste in batch considera quanto dura la clip.

Assemblare le opzioni in un oggetto

Metti tutte e tre le opzioni nella stessa struttura di opzioni, così c'è un solo posto da consultare e uno solo da modificare:

options = {
    "audio": True,          # genera la traccia audio
    "resolution": "...",    # uno dei valori supportati
    "duration": 8,          # secondi del video generato
}

Usa i valori elencati come supportati dal tuo account e dalla documentazione corrente dell'endpoint: leggili dalla documentazione invece di codificarli a caso, e validali durante la costruzione della richiesta, così un valore errato non diventa mai un'attività fallita.

Inviare l'attività con curl

Ora unisci le due parti e invia. Inizia dalla riga di comando, perché curl rende visibile la forma della richiesta e ti offre un modo rapido per testare le modifiche prima di scrivere codice.

La richiesta

L'invio ha strutturalmente questo aspetto: sostituisci i valori segnaposto con le tue credenziali, il riferimento all'immagine e i valori delle opzioni:

curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_frame": "<riferimento immagine dal passaggio di caricamento>",
    "audio": true,
    "resolution": "<valore supportato>",
    "duration": 8
  }'

Alcune convenzioni che vale la pena adottare:

  • Metti la chiave in una variabile d'ambiente ($HIAPI_API_KEY), invece di incollarla nel comando. Questa abitudine si trasferisce direttamente al tuo codice Python e tiene la chiave lontana dalla cronologia della shell.
  • Invia JSON con un header Content-Type esplicito.
  • Nel corpo della richiesta, separa il riferimento all'immagine dalle opzioni numeriche e booleane, rispecchiando il modello in due parti della prima sezione.

Leggere la risposta

Poiché si tratta di un endpoint asincrono, una risposta di successo non è il video. È solo la conferma che l'attività è stata accettata e contiene le informazioni necessarie per tracciarla, soprattutto l'identificatore dell'attività e di solito un campo di stato che indica che l'attività è in coda o in esecuzione.

Leggi la risposta in due passaggi. Primo, conferma che lo stato HTTP indichi accettazione e non un errore del client. Secondo, analizza il corpo della risposta ed estrai l'identificatore dell'attività:

curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | tee submit.json

Salvando la risposta in submit.json, avrai qualcosa da esaminare e da passare al passaggio di polling. Se l'invio fallisce, il corpo della risposta di errore è il tuo primo e miglior indizio: controlla se punta al riferimento all'immagine o a un'opzione, poi correggi solo quella metà e invia di nuovo.

Eseguire polling dell'attività asincrona fino alla disponibilità del video

Una volta ottenuto l'identificatore dell'attività, il flusso diventa un ciclo: chiedi alla piattaforma lo stato dell'attività e interrompi quando l'attività raggiunge uno stato terminale.

Ciclo di vita

Un'attività image-to-video attraversa un numero limitato di stati. Viene accettata e messa in coda, poi elaborata e infine o riesce producendo il video, oppure fallisce con un errore. Il tuo codice di polling deve solo distinguere tre casi:

  • Ancora in elaborazione: continua ad attendere.
  • Successo: leggi la posizione dell'output e scarica o memorizza il video.
  • Fallimento: interrompi e lancia un errore.

Eseguire polling in modo responsabile

Due abitudini rendono il polling più robusto:

  1. Attendi tra i controlli. Un ciclo stretto che martella l'endpoint di stato spreca richieste senza alcun beneficio; la generazione richiede tempo reale. Usa un intervallo fisso o un backoff moderato.
  2. Imposta una scadenza. Non eseguire mai polling all'infinito. Scegli un numero massimo di tentativi o un tempo massimo e considera il superamento come un fallimento da segnalare chiaramente.
# Bozza del ciclo di polling
for i in $(seq 1 60); do
  status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$status"
  # esci quando il campo di stato segnala successo o fallimento
  sleep 5
done

Considera le stringhe di stato esatte e i percorsi degli endpoint come elementi da verificare rispetto alla documentazione API corrente, non come assunzioni da fissare nello script.

In caso di successo

Quando l'attività segnala successo, la risposta contiene la posizione del video finale. Scaricalo tempestivamente e memorizzalo in una posizione persistente: i risultati delle attività su qualsiasi piattaforma asincrona vanno considerati come qualcosa da recuperare subito, non da caricare pigramente molto tempo dopo. Registra l'identificatore dell'attività insieme al file memorizzato, così ogni output è riconducibile alla richiesta che lo ha prodotto.

La stessa richiesta in Python

La versione Python non deve essere una seconda implementazione, ma la stessa richiesta espressa una volta e riutilizzata. L'obiettivo è una singola funzione che invia ed esegue polling, costruita con lo stesso riferimento all'immagine e lo stesso oggetto opzioni che hai già validato.

Un solo corpo della richiesta, un solo client

import os
import time
import requests

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

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
})

def build_body(first_frame_ref, options):
    return {"first_frame": first_frame_ref, **options}

def submit(body):
    r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
    r.raise_for_status()
    data = r.json()
    return data["job_id"]

def poll(job_id, interval=5, max_attempts=60):
    for _ in range(max_attempts):
        r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        state = data.get("status")
        if state in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"L'attività {job_id} non è stata completata in tempo")

def image_to_video(first_frame_ref, options):
    job_id = submit(build_body(first_frame_ref, options))
    result = poll(job_id)
    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "Attività fallita"))
    return result  # contiene la posizione del video finale

Perché questa forma

  • Una sola Session. Riutilizzare la sessione centralizza l'header di autenticazione e riutilizza la connessione tra l'invio e ogni polling.
  • Un solo build_body. La richiesta curl e quella Python usano lo stesso corpo: stesse chiavi, stessi valori. Quando modifichi un'opzione, la modifichi in un solo punto.
  • Timeout e scadenze espliciti. Entrambe le chiamate hanno un timeout e poll ha un limite di tentativi, così un'attività bloccata non blocca mai il tuo processo.
  • I fallimenti emergono chiaramente. raise_for_status all'invio intercetta subito gli errori a livello di richiesta; il ramo di fallimento esplicito in image_to_video intercetta i fallimenti a livello di attività.

Se in futuro dovrai chiamare altri modelli tramite la stessa piattaforma, questa struttura è generalizzabile: la sessione, la funzione ausiliaria di invio e quella di polling restano invariate, cambiano solo l'endpoint e il costruttore del corpo della richiesta.

Diagnosticare le chiamate image-to-video fallite

Quando una chiamata non produce un video, restringi il campo chiedendoti quale fase è fallita. Il modello della richiesta in due parti ti fornisce una checklist chiara.

Fase 1: invio rifiutato

Se la chiamata di invio stessa restituisce un errore, non è stato generato nulla: è una buona notizia, perché il problema è nella richiesta.

  • Problema con il riferimento all'immagine. È la singola causa più comune. Riesegui separatamente il passaggio di preparazione dell'immagine per confermare che produca un'immagine valida, leggibile e nel formato corretto, e un riferimento accettato dall'API. Controlla per primo caricamenti troncati e formati non supportati.
  • Valori delle opzioni non validi. Una risoluzione non supportata o una durata fuori intervallo vengono rifiutate all'invio. Valida le opzioni rispetto ai valori supportati nella documentazione prima di inviare.
  • Autenticazione e header. Conferma che la chiave venga effettivamente inviata (Authorization: Bearer ...) e che il corpo venga inviato come JSON. Quando costruisci richieste manualmente con curl, un corpo vuoto o malformato è facile da trascurare.

Fase 2: attività inviata ma fallita

Se l'invio è stato accettato ma il polling termina con un fallimento, la richiesta era nel formato corretto e il problema risiede nel contenuto o nell'attività stessa.

  • Leggi l'errore dell'attività. La risposta di fallimento spiega cosa è andato storto meglio di qualsiasi congettura. Registrala così com'è.
  • Esamina il primo fotogramma. Un'immagine di partenza senza soggetto chiaro, con ritagli estremi o distorsioni gravi offre al modello materiale insufficiente. Usa un fotogramma più pulito e riprova.
  • Riconsidera le opzioni. Una durata molto lunga o una combinazione insolita di impostazioni merita di essere ritestata con una configurazione più semplice per isolare quale parametro causa il problema.

Fase 3: il polling non termina mai

Se il tuo ciclo va in timeout invece di fallire, trattalo come un problema infrastrutturale, non di contenuto. Conferma che stai eseguendo polling sull'identificatore di attività corretto, che l'intervallo non sia troppo aggressivo e che la scadenza sia sufficientemente lunga per la durata richiesta. Registra l'identificatore dell'attività al momento dell'invio: senza di esso non puoi nemmeno indagare su un'attività bloccata.

Un flusso di debugging efficace

Quando qualcosa va storto, procedi in questo ordine: valida l'immagine in locale, invia di nuovo e cattura la risposta grezza, esamina l'eventuale errore dell'attività, poi semplifica le opzioni e riprova. Ogni passaggio verifica esattamente una metà della richiesta: ecco perché separare immagine e parametri di generazione nel codice ripaga proprio nel momento in cui si verificano errori.

A questo punto hai il ciclo completo: prepara il primo fotogramma, imposta audio, risoluzione e durata, invia in modo asincrono ed esegui polling fino al completamento. Che tu lo esegua con curl o con Python, è sempre la stessa richiesta.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API