HiAPI
Blog

Tutoriale

Come chiamare l'API veo-3.1 text-to-video: esempi curl e Python

Guida pratica all'integrazione per sviluppatori

Nov 17, 2026
Copertina in stile sezione trasversale di minerale sfaccettato piatto, in tonalità petrolio profondo, verde acqua e malachite, per il tutorial sull'API text-to-video veo-3.1.
In questa pagina

Cosa può fare veo-3.1/text-to-video per te

veo-3.1/text-to-video è un modello di generazione da testo a video esposto tramite l'API unificata di HiAPI. Invii un prompt testuale, scegli alcune opzioni di output e ricevi il video generato. Si trova su HiAPI insieme agli altri endpoint di generazione, quindi se usi già le capacità di immagini o chat della piattaforma, questa modalità di integrazione ti risulterà familiare: una singola richiesta HTTP autenticata restituisce un job e poi esegui il polling finché il job non è completato.

Questo endpoint è la scelta giusta quando hai una descrizione testuale di una scena e vuoi generare un breve video senza gestire tu stesso l'infrastruttura. Non devi occuparti dell'allocazione delle GPU, dei pesi del modello o delle code. Il prezzo da pagare è che la generazione è asincrona: invii il job e torni più tardi a controllare il risultato. È la norma per i video, perché il rendering richiede più tempo di un singolo ciclo richiesta/risposta.

Usa il text-to-video quando l'input principale è un prompt. Se in seguito ti servono generazioni condizionate da immagini o video, consulta gli endpoint corrispondenti nel catalogo dei modelli. La struttura della richiesta qui (autenticazione, invio del job, polling) è lo stesso schema che riutilizzerai negli endpoint media di HiAPI, quindi impararlo una volta ti servirà a lungo. Trovi tutti i dettagli del modello nella pagina del modello veo-3.1/text-to-video.

Endpoint, autenticazione e struttura della richiesta

Tutte le richieste a HiAPI usano HTTPS e un bearer token. Conserva la tua chiave API in una variabile d'ambiente invece di scriverla nel codice, e inviala nell'header Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Una richiesta text-to-video è un oggetto JSON con un campo model e un oggetto input. L'oggetto input contiene il prompt e qualsiasi controllo di output. Il corpo minimo della richiesta è questo:

{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "Di notte attraverso un vicolo al neon bagnato dalla pioggia, lenta carrellata in avanti"
  }
}

Quello che ricevi non è il video finale, ma una busta del job. Di solito contiene l'identificatore del job, un campo di stato e un timestamp. La struttura è più o meno questa:

{
  "id": "job_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

Per i nomi esatti dei campi fai riferimento alla risposta reale, ma la struttura è coerente: ti serve id per il polling, mentre status ti dice se il job è in coda, in esecuzione o completato. Non dare per scontato che il job sia completato solo perché la chiamata di invio ha restituito 200: significa solo che il job è stato accettato.

Scegliere i parametri: audio nativo e livelli di risoluzione

Oltre al prompt, i parametri più importanti per il text-to-video sono se generare l'audio nativo e il livello di risoluzione desiderato. Entrambi influiscono sul tempo di generazione e sulla natura dell'output, quindi scegli con consapevolezza invece di usare i valori predefiniti alla cieca.

Audio nativo

Alcuni modelli video possono generare una traccia audio insieme alle immagini. Se l'endpoint offre un interruttore per l'audio nativo, abilitarlo significa che la clip generata include un suono sincronizzato. È utile per scene in cui l'audio è parte integrante dell'esperienza: rumore ambientale, musica o effetti sonori abbinati all'azione. Se prevedi di aggiungere in post-produzione la tua colonna sonora o una voce fuori campo, disabilitalo e concentra l'output sulle immagini. Anche la generazione audio aumenta i tempi di elaborazione, quindi abilitala solo se ti serve davvero.

Livelli di risoluzione

I livelli di risoluzione ti permettono di bilanciare fedeltà visiva, costo e latenza. I livelli più alti producono output più nitidi ma richiedono più tempo e consumano più risorse. Scegli il livello più basso che soddisfa il tuo obiettivo di consegna: un livello bozza per iterare e rivedere, un livello più alto per il rendering finale. Se devi generare molti candidati da un unico prompt, esplora con un livello inferiore e rigenera a piena qualità quello vincente. La fatturazione segue l'output generato, quindi scegliere il livello in modo consapevole è la leva principale che hai a disposizione.

Se non sei sicuro di quali valori accetta attualmente l'endpoint, invia una richiesta solo con il prompt e poi controlla la risposta o il messaggio di errore. HiAPI restituisce errori di validazione strutturati che elencano i campi accettabili, così puoi adattarti di conseguenza senza tirare a indovinare.

Richiesta curl eseguibile

Questo comando curl invia un job text-to-video. Imposta il tipo di contenuto JSON, passa il bearer token dalla variabile d'ambiente e invia il corpo della richiesta con model e input.

curl -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/text-to-video",
    "input": {
      "prompt": "Di notte attraverso un vicolo al neon bagnato dalla pioggia, lenta carrellata in avanti",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Una chiamata riuscita restituisce un oggetto JSON con l'id e lo status del job. Annota questo id: ti servirà per il polling. Se stai scrivendo uno script, puoi estrarre l'id dall'output con un processore JSON:

JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Di notte attraverso un vicolo al neon bagnato dalla pioggia, lenta carrellata in avanti"}}' \
  | jq -r '.id')
echo "$JOB_ID"

Adatta il percorso dell'endpoint, i nomi dei parametri e gli eventuali campi opzionali a quanto si aspetta l'API reale. Questo schema — inviare via POST un corpo JSON e leggere l'id dalla risposta — è la base di ogni esempio successivo.

Inviare la stessa richiesta con Python

La versione Python fa la stessa cosa usando la libreria standard requests. Legge la chiave dall'ambiente, costruisce il payload e lo invia.

import os
import requests

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

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

payload = {
    "model": "veo-3.1/text-to-video",
    "input": {
        "prompt": "Di notte attraverso un vicolo al neon bagnato dalla pioggia, lenta carrellata in avanti",
    },
}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()

job = response.json()
job_id = job["id"]
print(f"Job inviato: {job_id} (stato: {job.get('status')})")

Due cose meritano di essere sottolineate. Primo, response.raise_for_status() trasforma gli errori HTTP in eccezioni, rendendo immediatamente visibile un fallimento invece di lasciare che un payload corrotto passi in silenzio. Secondo, timeout=60 evita che una connessione bloccata blocchi il tuo script. L'invio in sé è rapido; il video vero e proprio viene renderizzato in modo asincrono, quindi non aspetti qui il file. Poi userai job_id per fare polling fino al completamento.

Fare polling del job asincrono fino a quando il video è pronto

Dopo l'invio, esegui il polling dell'endpoint del job finché lo stato non indica completamento o fallimento. Un semplice ciclo con una breve pausa è più che sufficiente per iniziare.

import time

while True:
    res = requests.get(
        f"{BASE_URL}/videos/generations/{job_id}",
        headers=headers,
        timeout=30,
    )
    res.raise_for_status()
    state = res.json().get("status")
    print(f"Stato: {state}")

    if state == "succeeded":
        video_url = res.json().get("output", {}).get("url")
        print(f"Video pronto: {video_url}")
        break
    if state == "failed":
        raise RuntimeError(f"Job fallito: {res.json()}")

    time.sleep(5)

Alcuni miglioramenti utili: inizia con un intervallo breve e poi aumenta progressivamente il backoff per ridurre le richieste sprecate; aggiungi un numero massimo di tentativi o una scadenza per evitare cicli infiniti su job bloccati; e tratta con cautela qualsiasi stato inatteso invece di dare per scontato che significhi "continua ad aspettare". I valori di stato comuni includono queued, running, succeeded e failed. Quando il job riesce, la risposta di solito contiene l'URL dell'output; scarica e salva il file tempestivamente, perché gli URL firmati possono scadere.

Rendi il polling idempotente e registra l'id del job a ogni cambio di stato. Se il tuo processo si riavvia, puoi riprendere per id senza reinviare. In produzione, se la piattaforma offre webhook, valuta di usarli, con il polling come fallback.

Diagnosticare gli errori più comuni

La maggior parte dei fallimenti rientra in poche categorie. Segui la checklist qui sotto in ordine, invece di riprovare alla cieca.

Errori di autenticazione (401/403)

Verifica che l'header Authorization sia presente e formattato correttamente come Bearer <key>, e che la variabile d'ambiente sia effettivamente impostata nella shell o nel processo che effettua la richiesta. Una trappola comune è eseguire lo script in un ambiente in cui la chiave esiste in una shell ma non in un'altra.

Errori di validazione (400/422)

Questi errori restituiscono dettagli strutturati su quale campo è errato. Cause comuni: prompt mancante, valori non supportati di resolution o duration, o annidamento dei parametri errato. Prendi alla lettera il messaggio di errore: di solito indica il campo problematico. Invia prima un payload minimo, poi aggiungi un parametro alla volta.

Limiti di frequenza (429)

Stai inviando richieste troppo velocemente. Implementa un backoff esponenziale e un limite ai tentativi. Se devi avviare molti job, scagliona gli invii e tieni traccia dei job in corso.

Timeout ed errori di rete

Un timeout del client al momento dell'invio raramente è un problema del job stesso: il job viene eseguito sul server. Usa timeout ragionevoli sia per l'invio sia per il polling, e ritenta le richieste GET idempotenti. Non ritentare mai un POST alla cieca senza controllare se il job originale è già stato creato.

Il job non si completa mai

Se un job resta in queued o running molto più del previsto, controlla il codice di stato e il messaggio invece di reinviarlo. Prompt lunghi o livelli di risoluzione più alti richiedono più tempo; è normale. Se il job riporta failed, registra l'intero corpo della risposta: il messaggio di errore di solito indica la causa.

In caso di dubbio, riproduci il problema con la richiesta più piccola possibile e controlla ogni risposta. È molto meglio che modificare più parametri insieme e poi indovinare quale fosse importante. Per i dettagli specifici dell'endpoint, consulta la pagina del modello.

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