Come chiamare flux-3-video tramite l'API HiAPI: esempi di richiesta funzionanti con curl, Python e casi reali

Cosa offre flux-3-video tramite l'API

Prima di scrivere la prima riga di codice, è utile capire cosa può fare realmente il modello flux-3-video tramite l'API HiAPI. La famiglia di endpoint copre due modalità di chiamata che condividono la stessa struttura di richiesta, oltre a una capacità audio opzionale che puoi abilitare o ignorare in base al caso d'uso.

Le due modalità di chiamata

• Text-to-video — invii un prompt testuale e ricevi una clip video appena generata. Usa questa modalità quando hai solo un'idea e vuoi che il modello generi movimento, composizione e ritmo.
• Continuazione video — invii una clip video esistente (o un suo riferimento) insieme a un'istruzione, e il modello la estende. Usa questa modalità quando hai già un materiale e vuoi ottenere più contenuto senza giunture visibili.

Audio nativo

Il modello può anche produrre audio nativo insieme al video, controllato tramite parametri opzionali nello stesso payload della richiesta. Poiché questi parametri sono opzionali, i flussi di lavoro solo video possono ignorarli completamente: basta omettere i campi audio e la richiesta si comporta esattamente come se non esistessero.

Il modello mentale centrale su cui si basano le sezioni successive è questo: non sono due API separate, né due tutorial distinti. Sono due forme della stessa richiesta; una volta compreso lo scheletro condiviso, passare dall'una all'altra significa semplicemente sostituire alcuni input. Tutto il resto — credenziali, header, identificatore del modello, gestione della risposta — rimane invariato.

Questo design è intenzionale. Significa che il codice di autenticazione, la gestione degli errori, la logica di retry e il parsing della risposta vanno scritti una sola volta e possono essere riutilizzati in entrambe le modalità; aggiungere l'audio in seguito non ti costringerà a riscrivere nulla.

Autenticazione, endpoint e anatomia della richiesta

Ogni chiamata a flux-3-video segue lo stesso scheletro. Imparalo una volta e le due modalità diventano varianti dello stesso tema.

Credenziali

HiAPI autentica le richieste tramite una API key. La passi nell'header, di solito come bearer token. Non inserire la chiave nel codice sorgente: leggila da una variabile d'ambiente o da un gestore di segreti, assicurandoti che non finisca mai nel sistema di controllo versione:

export HIAPI_API_KEY="your-key-here"

Endpoint e identificatore del modello

La chiamata va all'URL di base dell'API HiAPI, e il payload specifica esplicitamente il modello tramite l'identificatore flux-3-video. Mettere il nome del modello nel corpo della richiesta anziché codificarlo nell'URL significa che lo stesso codice client può puntare a un altro modello in futuro cambiando una sola riga.

La struttura condivisa del payload

In entrambe le modalità, il payload è un oggetto JSON che concettualmente contiene tre parti:

• Il campo model — sempre flux-3-video.
• Gli input che definiscono la modalità — nel text-to-video è un prompt; nella continuazione è la clip sorgente più un prompt. Questa è l'unica parte che cambia sostanzialmente tra le due modalità.
• Modificatori opzionali — parametri audio e altre regolazioni. Ometterli produce il comportamento predefinito.

La pseudo-struttura di una richiesta è la seguente:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

L'idea generale è questa: un identificatore del modello, un oggetto annidato input che contiene i campi specifici della modalità, e chiavi opzionali aggiunte solo quando necessario. Le sezioni successive illustrano i dettagli specifici di ciascuna modalità.

Text-to-video: la tua prima richiesta curl funzionante

Ecco una richiesta minima ma completa che genera un video da un prompt. Presuppone che HIAPI_API_KEY sia già esportata nella tua shell.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

Cosa fa ciascun campo

• Authorization — trasporta il tuo bearer token. Senza di esso, la richiesta viene rifiutata prima che inizi qualsiasi generazione.
• Content-Type: application/json — il corpo della richiesta è JSON, quindi dichiaralo; ometterlo è una causa comune di risposte 4xx confuse.
• model — identifica flux-3-video come modello di destinazione.
• input.prompt — l'unico input creativo obbligatorio nella modalità text-to-video. Scrivilo come descriveresti un'inquadratura: soggetto, movimento, composizione, luce, atmosfera.

Consigli sulla scrittura dei prompt che valgono la pena

Poiché il prompt è l'unica leva creativa in questa modalità, la sua qualità determina direttamente il risultato. Due abitudini aiutano:

• Descrivi il movimento, non solo il contenuto. "A dolly shot through…" (un carrello che attraversa…) dà al modello un comportamento di camera da animare; una descrizione statica non gli lascia nulla su cui lavorare.
• Sii specifico. Indizi concreti su luce e materiali ("wet asphalt", "neon reflections") producono spesso immagini più coerenti rispetto ad aggettivi astratti.

Dopo aver eseguito questa richiesta e aver esaminato la risposta, hai verificato la chiave, gli header e il payload di base: le fondamenta di tutto il resto.

Continuazione video: estendere una clip esistente

La continuazione riutilizza lo scheletro della sezione precedente, ma la forma dell'oggetto input cambia. Il prompt non esiste più da solo, ma viene abbinato alla clip sorgente che il modello deve estendere.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

Cosa cambia rispetto al text-to-video

• Compare un input video. Fornisci la clip esistente su cui il modello deve costruire. Questa è la differenza decisiva tra le due modalità.
• Il prompt diventa direttivo, non generativo. Nel text-to-video descrivi l'intera scena; qui descrivi cosa succede dopo. Scrivilo come istruzione di continuazione: dove va la camera, cosa entra nell'inquadratura, come si evolve la scena.
• Tutto il resto è identico. Stesso endpoint, stessi header, stesso identificatore del modello, stesso wrapper input. Il tuo codice client deve ramificarsi solo al momento di costruire il payload.

Mantenere la coerenza alla giuntura

Il modello deve corrispondere all'aspetto della clip sorgente per evitare tagli visibili. Istruzioni brevi e specifiche che preservano lo stile esistente funzionano spesso meglio di lunghe descrizioni che reimmaginano la scena. Se la prima continuazione deriva, avvicina il prompt al contenuto effettivo della clip sorgente invece di aggiungere più dettagli altrove.

Nota sui riferimenti alle clip

La convenzione esatta di input per la clip sorgente è definita dallo schema di input del modello su HiAPI. Segui quello schema invece di indovinare il formato del campo: è la fonte autorevole su cosa accetta l'input di continuazione.

Aggiungere i parametri audio nativi

L'audio nativo è dove il pattern dei modificatori opzionali dimostra il suo valore. I parametri audio risiedono nello stesso oggetto input degli altri campi, e poiché sono opzionali, le richieste delle due sezioni precedenti restano valide senza di essi.

Dove si trovano

Le impostazioni audio stanno dentro input, accanto a prompt e (in modalità continuazione) a video. Concettualmente:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

Mantenere sicuri i flussi di lavoro solo video

La disciplina importante qui è semplice: tratta il blocco audio come puramente additivo.

• Non impostare esplicitamente i campi audio su un valore "off" — omettili. Un blocco assente è più pulito di uno disabilitato esplicitamente e meno soggetto a conflitti con future modifiche dello schema.
• Costruisci il payload in modo incrementale. Parti dal corpo minimo della richiesta e aggiungi la chiave audio solo nei percorsi di codice in cui l'utente richiede effettivamente l'audio. Così il tuo percorso predefinito rimane identico agli esempi solo video.
• Prima di integrare l'audio in produzione, consulta lo schema per confermare i nomi esatti dei flag e i valori accettati. La denominazione dei parametri è definita dallo schema di input del modello su HiAPI; il blocco qui sopra mostra solo la posizione, non garantisce l'ortografia dei campi.

Quando abilitarlo

Abilita l'audio quando il risultato è una clip video finita e autosufficiente: contenuti per social media, presentazioni, brevi opere narrative. Lascialo disattivato quando aggiungerai a valle una tua colonna sonora o voce fuori campo; generare audio che poi scarterai è uno spreco di capacità di calcolo nella pipeline.

Poiché l'audio viaggia nello stesso payload di tutto il resto, non ci sono chiamate separate, seconde credenziali, né rami aggiuntivi di gestione della risposta oltre a leggere ciò che la risposta restituisce.

Scrivere la stessa richiesta in Python

Trasporre la chiamata curl in Python è un lavoro meccanico, perché la struttura della richiesta è identica. L'esempio seguente usa solo la libreria standard, quindi funziona in qualsiasi ambiente; se preferisci requests o httpx, la struttura si mappa direttamente.

import json
import os
import urllib.request

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

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

Perché è organizzato così

• Una funzione, due modalità. Il parametro video è opzionale; quando è None, la funzione genera una richiesta text-to-video. Quando è impostato, la stessa funzione genera una richiesta di continuazione. Nessun client separato, nessun header duplicato.
• L'audio va abilitato esplicitamente. Il flag audio è False per impostazione predefinita, quindi il blocco audio non viene mai aggiunto se non richiesto esplicitamente: questo è esattamente il pattern descritto sopra.
• La chiave proviene dall'ambiente. La API key viene letta da HIAPI_API_KEY e non è mai codificata nel codice.

Per adattarlo, sostituisci semplicemente le chiamate a print con l'operazione richiesta dalla tua pipeline: scrivere la risposta in un manifest, accodare attività successive o notificare una coda. La logica della richiesta stessa non deve cambiare.

Risoluzione dei problemi e checklist per la produzione

Quando una chiamata fallisce, esamina la seguente lista in ordine: copre la stragrande maggioranza dei problemi.

Lista di diagnostica

• 401 o errore di autenticazione — HIAPI_API_KEY è davvero esportata nella shell o nel processo che esegue il codice? Una chiave impostata in un terminale non viene ereditata da un cron job.
• 415 o errore di parsing imprevisto — Content-Type: application/json è presente? Ometterlo è il classico fallimento silenzioso.
• La chiamata di continuazione restituisce 4xx — il tuo payload include la clip sorgente nella forma attesa dallo schema di input del modello? Un riferimento alla clip malformato fallisce prima che inizi la generazione.
• L'audio manca nell'output — il blocco audio è effettivamente finito nel payload? Durante il debug registra il corpo della richiesta serializzato; costruire un dizionario e dimenticare di allegare la chiave è un errore facile da commettere.
• input vuoto o troncato — stampa il JSON esatto che stai effettivamente inviando. Quasi ogni fallimento "strano" si risolve guardando con i propri occhi il corpo della richiesta in transito.

Prima di andare in produzione

• Non codificare mai le chiavi nel codice. Usa sempre variabili d'ambiente o un gestore di segreti.
• Registra sia il corpo della richiesta sia quello della risposta, almeno in preproduzione. Riprodurre un fallimento senza il payload esatto è solo un'ipotesi.
• Tratta i campi opzionali come opzionali. Costruisci il payload in modo incrementale: prima il corpo minimo, poi aggiungi video, infine audio solo se necessario. Questo mantiene il tuo percorso predefinito allineato agli esempi della documentazione.
• Mantieni la scelta della modalità esplicitamente visibile nel tuo codice. Una funzione con un parametro video opzionale va bene; un booleano sepolto a tre livelli di profondità no.
• Ogni volta che aggiungi un campo, riconsulta lo schema di input del modello su HiAPI. È il riferimento autorevole per nomi dei parametri e formati accettati, ed è più aggiornato di qualsiasi tutorial.

Il punto chiave merita di essere ripetuto: text-to-video, continuazione e audio nativo sono tre varianti della stessa forma di richiesta. Impara lo scheletro una volta e ogni nuova capacità è solo una modifica aggiuntiva, non una riscrittura. Buona costruzione.