Come chiamare flux-3-max/text-to-video tramite l'API HiAPI: guida con curl e Python

Funzionalità e scenari d'uso di flux-3-max/text-to-video

flux-3-max/text-to-video è l'endpoint text-to-video su HiAPI: invii un prompt che descrive una scena e il modello restituisce una clip video generata. È lo strumento adatto quando hai un'idea testuale e non materiale pronto — ad esempio un teaser di prodotto, un breve video per i social, un'anteprima di storyboard o una serie di riprese di sfondo generate in batch — e desideri che il processo di generazione sia un'attività gestita anziché eseguita in proprio.

È adatto a flussi di lavoro in cui il video è solo un anello di una catena più ampia. Un generatore di script produce i prompt, flux-3-max/text-to-video li trasforma in clip video e la tua applicazione si occupa di archiviare o distribuire il risultato. Poiché la chiamata è asincrona, è adatto anche a servizi backend che non possono mantenere una richiesta aperta per l'intera durata del rendering.

Non usarlo quando devi fare editing frame-accurate su un video esistente o quando il tuo prompt è in realtà solo un'immagine statica: per quest'ultimo caso l'endpoint text-to-image è più economico e più veloce. Se l'output deve reagire a materiale fornito, occorre usare la variante image-to-video. Considera flux-3-max/text-to-video come il punto d'ingresso per la generazione di clip video a partire da un prompt e progetta la tua integrazione attorno all'invio di un task anziché a una risposta sincrona.

Struttura della richiesta: endpoint, autenticazione e payload

Ogni richiesta a flux-3-max/text-to-video comprende tre parti: il percorso dell'endpoint, l'header di autenticazione e un corpo JSON che indica il modello e i suoi input.

Autenticazione

HiAPI usa token bearer. Inserisci la tua chiave API nell'header Authorization:

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

Mantieni la chiave lato server. Non incorporarla nel codice client né salvarla nel repository; durante lo sviluppo caricala da una variabile d'ambiente, in produzione da un gestore di segreti.

Identificatore del modello

Nel corpo della richiesta, il campo model seleziona l'endpoint. Usa l'identificatore esatto flux-3-max/text-to-video; un errore di battitura qui è la causa più comune di richieste rifiutate.

Struttura del payload

Il corpo minimo contiene il nome del modello e il prompt:

{
  "model": "flux-3-max/text-to-video",
  "prompt": "All'alba, una lenta ripresa aerea sopra una pineta avvolta nella nebbia, illuminazione cinematografica"
}

I campi opzionali — durata e interruttore dell'audio nativo — sono descritti nella sezione successiva. Poiché la generazione è asincrona, la risposta immediata a questa richiesta POST è un oggetto task con un identificatore che dovrai interrogare, anziché il video finito. Progetta il codice in modo che legga prima quell'identificatore e il resto dopo.

Controllare durata e audio nativo

Due controlli a livello di richiesta determinano il risultato: la durata della clip e se il modello genera l'audio insieme al video.

Durata

Imposta la lunghezza della clip tramite il campo duration nel payload. Scegli la durata più breve che soddisfa la narrazione: le clip brevi si renderizzano più in fretta, sono più facili da revisionare e puoi sempre richiederne un'altra. Prima dell'invio, verifica il valore rispetto all'intervallo documentato di flux-3-max/text-to-video; durate fuori intervallo vengono rifiutate al momento dell'invio, e intercettare il problema in locale fa risparmiare un round-trip.

Audio nativo

L'interruttore dell'audio nativo decide se il modello genera una traccia audio insieme alla clip. Attivalo quando il video sarà guardato con l'audio, disattivalo quando il video sarà silenziato, sottotitolato o musicato separatamente in post-produzione. Generare audio che poi scarterai aggiunge solo tempo al task senza alcun beneficio.

Scegliere consapevolmente

Evita di lasciare che i valori predefiniti decidano per te. Per una rapida revisione di uno storyboard, una clip breve e muta è di solito sufficiente. Per un contenuto social definitivo, una clip più lunga con audio nativo può essere l'obiettivo. Codifica questa scelta nella configurazione dell'applicazione, anziché codificarla a mano nel punto di chiamata, così potrai modificarla per funzionalità senza toccare il codice della richiesta. Invia solo i campi che vuoi davvero sovrascrivere e lascia che l'endpoint applichi i propri valori predefiniti per gli altri.

Richiesta curl pronta all'uso

Il modo più rapido per verificare credenziali e payload è inviare un task con una singola chiamata curl.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "Una barchetta di carta galleggia lungo una strada bagnata dalla pioggia, lampioni caldi, profondità di campo ridotta",
    "duration": 5,
    "native_audio": false
  }'

Imposta prima HIAPI_BASE_URL e HIAPI_API_KEY nella shell. I valori di durata e audio qui sono solo esempi: usa valori compresi nell'intervallo documentato per il modello.

Leggere la risposta immediata

La risposta è un oggetto task, non un video. Contiene un job_id (o identificatore equivalente) e uno stato come queued o processing. Salva l'identificatore: è il riferimento per tutte le chiamate successive. Se la risposta sembra essere un oggetto di errore, controlla codice di stato e messaggio prima di riprovare: un payload malformato fallisce allo stesso modo ogni volta.

Un invio riuscito significa solo che il task è stato accettato, nulla di più. Non cercare l'URL del video nella prima risposta: non comparirà finché il task non sarà completato.

Gestire il ciclo di vita di un task asincrono

La generazione video richiede da pochi secondi a diversi minuti, perciò HiAPI la modella come task. Il tuo client invia una volta e poi controlla lo stato finché il task raggiunge uno stato terminale.

Stati

Il task passa da queued a processing e poi a uno stato terminale: completed o failed. Solo lo stato terminale è definitivo; qualsiasi stato intermedio significa che devi continuare ad attendere.

Eseguire polling senza martellare

Interroga l'endpoint di stato usando l'identificatore del task salvato. Due regole mantengono il polling sano:

• Attendi tra un polling e l'altro. Parti con un intervallo breve e introduci un backoff progressivo, oppure usa un intervallo fisso chiaramente più lungo del tempo tipico in coda. Martellare l'endpoint di stato non porta alcun beneficio.
• Imposta un limite. Limita il tempo totale di attesa e il numero totale di tentativi. Se a quel punto il task non è ancora completato, segnalalo alla tua applicazione anziché restare in un ciclo infinito.

Nei gestori Web, non bloccare il thread della richiesta su un ciclo di polling. Invia, salva l'identificatore del task, restituisci subito e lascia che un worker in background o il client completi il ciclo di vita tramite polling. In scenari batch, un semplice ciclo con sleep è sufficiente.

Leggere il risultato

Quando il task risulta completed, la risposta include un riferimento all'output: l'URL del video o un handle del materiale che la tua applicazione può scaricare o trasmettere in streaming. In caso di fallimento, leggi il campo error; di solito indica la causa (parametri non validi, rifiuto dei contenuti, errore interno). Registra insieme l'identificatore del task e il messaggio di errore, così le richieste di supporto o i tentativi successivi avranno basi solide. Non considerare mai riuscita una risposta solo perché il campo di output manca: controlla esplicitamente lo stato.

La stessa richiesta in Python

Il flusso curl si trasferisce direttamente in Python. Un client minimo richiede l'invio, il ciclo di polling e una gestione degli errori sufficiente a distinguere una richiesta errata da un task lento.

import os, time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

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

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

Note sull'implementazione

raise_for_status() distingue gli errori di trasporto e HTTP (autenticazione, payload malformato) dai fallimenti a livello di task, che compaiono dentro una risposta riuscita. Il controllo failed legge esplicitamente il campo error anziché presumere che lo stato sia completed. Il limite al numero di tentativi trasforma un'attesa illimitata in un'eccezione prevedibile.

In produzione, avvolgi il polling in una strategia di retry per gli errori di rete transitori e riutilizza un singolo requests.Session. Se esegui molti task, sposta wait in un worker anziché nel percorso della richiesta.

Diagnosi dei fallimenti comuni

La maggior parte dei problemi di integrazione rientra in poche categorie. Ognuna ha un metodo di verifica concreto.

Errori di autenticazione

401 o 403 significano che la chiave è mancante, scaduta o malformata. Verifica che l'header Authorization sia presente, che usi lo schema Bearer e che la variabile d'ambiente sia effettivamente popolata nel runtime, non solo nella tua shell.

Payload malformato

400 di solito significa che il corpo della richiesta non rispetta lo schema. Verifica che il JSON sia analizzabile, che model sia esattamente flux-3-max/text-to-video e che la richiesta invii Content-Type: application/json. Usa una libreria JSON per serializzare, anziché costruire stringhe a mano.

Valori dei parametri non validi

Una durata fuori dall'intervallo documentato, un nome di campo sconosciuto o un tipo errato per l'interruttore audio causano il rifiuto al momento dell'invio. Convalida in locale rispetto ai parametri documentati del modello prima di inviare.

Polling troppo presto

Interrogare subito e ripetutamente dopo l'invio non fa completare il task più in fretta. Usa un backoff o un intervallo fisso e lascia che sia l'oggetto task a dirti quando ha superato lo stato queued.

Fallimenti del task non gestiti

Un task arrivato a failed non significa necessariamente che la tua richiesta abbia un bug: può essere un rifiuto dei contenuti o un errore interno. Leggi il messaggio di errore, registra l'identificatore del task e decidi se riprovare con un prompt modificato o segnalare il problema.

Trattare la risposta di invio come risultato

Se il tuo codice si aspetta l'URL del video subito dopo l'invio, andrà in errore. La prima risposta è un task; solo lo stato terminale contiene l'output. Una volta che questi sei controlli sono in atto, la maggior parte dei problemi di integrazione si risolve.