Come utilizzare l'API hiapi per l'editing video AI con flux-3

Qui "editing" ha un significato specifico: flux-3 (FLUX.3 Video, di Black Forest Labs) estende una clip esistente — ne prosegue il movimento, il movimento di camera e l'audio, generando nuove immagini — oppure costruisce un'inquadratura a partire da un insieme ordinato di immagini chiave. Non ritaglia, taglia, maschera, corregge il colore o esegue altre operazioni sul materiale esistente. Se sei qui cercando un editor, le FAQ qui sotto sono il modo più rapido per capire se flux-3 fa davvero al caso tuo prima di scrivere qualsiasi codice.

Ciò in cui eccelle davvero: prendere un video che hai già e generarne una continuazione, mantenendo lo stesso soggetto, lo stesso linguaggio di ripresa e l'audio — utile per prolungare un'inquadratura che finisce troppo presto, oppure per concatenare più clip generate in un'unica inquadratura più lunga. L'altra modalità riceve un insieme di immagini statiche come fotogrammi chiave ordinati e genera il movimento tra di esse, come un montaggio basato su uno storyboard, anche se non è coinvolto alcun video esistente.

1. Cosa ti serve

Una chiave API hiapi dalla dashboard (sk-...). flux-3, come tutti gli altri modelli hiapi, si chiama tramite l'API task unificata, quindi qui non c'è nessuna configurazione specifica del modello — se hai già chiamato qualsiasi altro modello video hiapi, hai già tutto ciò che ti serve.

2. Esempio minimo funzionante

Crea un task, poi esegui il polling (oppure usa un callback — vedi Pattern di produzione) finché non raggiunge uno stato terminale.

# 1. Crea il task — modalità continuazione (start_video)
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "continuare la panoramica, la camera continua a spostarsi verso destra, mantenendo la stessa illuminazione",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Esegui il polling fino allo stato terminale
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video è un URL HTTPS pubblico che punta a un MP4 (il materiale di origine è limitato a 50MB e 15 secondi) — è la clip che flux-3 continua. duration è un numero intero da 5 a 20 secondi e controlla la lunghezza della parte nuova generata, non la lunghezza dell'output composito. resolution è 720p o 1080p; aspect_ratio accetta auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 o 9:16. generate_audio è un booleano — quando è true, i suoni ambientali generati dal modello vengono incorporati direttamente nell'MP4 di output, invece di essere un file audio separato. Imposta draft: true mentre iteri il prompt; i task in bozza sono più economici, ma forzano resolution a 720p (le richieste con draft: true e resolution: "1080p" insieme vengono rifiutate).

Storyboard a fotogrammi chiave (non editing di materiale esistente)

L'altra modalità di input usa image_urls al posto di start_video — un array ordinato da 1 a 10 URL di immagini che flux-3 tratta come uno storyboard, generando il movimento che le collega in sequenza:

{
  "model": "flux-3",
  "input": {
    "prompt": "carrellata fluida attraverso ogni scena in sequenza",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls e start_video sono due forme di task diverse sullo stesso modello — non inviarle entrambe nella stessa richiesta. Usa image_urls quando costruisci un'inquadratura da zero a partire da immagini statiche; usa start_video quando hai materiale generato (o di origine) che vuoi continuare in avanti.

3. Pattern di produzione

Su larga scala usa i callback invece del polling. Passa un oggetto callback nello stesso corpo della richiesta, invece di eseguire il polling in un ciclo:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" scatta una sola volta, quando il task raggiunge un qualsiasi stato terminale — sia succeeded che failed sono stati terminali, quindi deduplica il tuo handler webhook per taskId, invece di dare per scontato che un callback significhi solo successo. Il polling con GET /v1/tasks/:id è più adatto al debug locale, ai task una tantum a bassa frequenza, o come fallback di riconciliazione quando un callback non arriva.

Idempotenza. Se non stai attento, i retry dopo un timeout o una connessione interrotta possono creare task duplicati (e fatturabili) — tieni traccia dell'id del task restituito dalla chiamata di creazione e, prima di considerare l'invio di un nuovo task, trasforma il retry in una GET su quell'id.

Gli URL di output scadono. Il campo expireAt su ogni voce di output non è decorativo — che tu abbia appreso del successo del task da un callback o dal polling, scarica il video e salvalo nel tuo storage immediatamente dopo il successo del task.

Errori di autenticazione. Una chiave errata o mancante restituisce HTTP 401 con {"error": {"code": "permission_denied", ...}}. Controlla esplicitamente quello stato/codice, invece di dare per scontato che qualsiasi risposta non-2xx significhi che la generazione stessa è fallita — "la mia chiave è sbagliata" e "il modello ha rifiutato il mio input" richiedono correzioni diverse.

Valida gli URL dei media prima dell'invio. start_video e image_urls controllano tipo e formato, ma non verificano che il file a quell'URL esista davvero o sia decodificabile — un URL sintatticamente valido ma non raggiungibile crea comunque un task, che poi fallisce dopo qualche secondo, invece di essere rifiutato all'invio. Prima di collegare gli URL a un batch di task, verifica che si risolvano davvero.

4. Pagine correlate

• Pagina del modello flux-3 — riferimento completo dei parametri, playground e i prezzi correnti al secondo e per risoluzione per tutte e tre le modalità (testo a video, storyboard a fotogrammi chiave e continuazione).
• Documentazione sulla creazione dei task — riferimento completo di richiesta/risposta per /v1/tasks, incluse le opzioni di callback.
• Documentazione sull'autenticazione — come funzionano l'header Authorization: Bearer sk-... e gli scope delle chiavi.
• Controllo del primo e ultimo fotogramma nei video AI — un approccio correlato, adatto ai modelli che interpolano tra due fotogrammi statici, se la modalità storyboard multi-fotogramma chiave di flux-3 non è abbastanza precisa per la tua inquadratura.
• Prezzi hiapi — tariffe correnti (la continuazione costa più della generazione standard, e la modalità bozza costa meno di entrambe — consulta la pagina live, invece di numeri codificati a mano).

5. Domande frequenti

flux-3 può ritagliare, tagliare, mascherare o correggere il colore di un video esistente? No. La modalità "video a video" di flux-3 è la continuazione — genera immagini nuove, proseguendo il soggetto, il movimento di camera e l'audio della clip di origine. Non modifica i fotogrammi già esistenti. Attualmente nessun modello hiapi esegue editing di timeline (ritaglio/taglio) o editing di aree mascherate su un video.

Qual è la differenza tra continuazione e storyboard a fotogrammi chiave? La continuazione (start_video) richiede un file video esistente e lo estende. Lo storyboard a fotogrammi chiave (image_urls) richiede solo immagini statiche e genera il movimento tra di esse — non serve alcun video di origine. Sono input mutuamente esclusivi sullo stesso id di modello flux-3.

Posso usare start_video e image_urls insieme in una sola richiesta? No — ogni task sceglie una modalità. Inviarli entrambi non è una forma di input supportata.

draft: true funziona in modalità continuazione? Sì, ed è il modo più economico per iterare il prompt di continuazione prima di inviare un'esecuzione a piena risoluzione — ma, come nella modalità standard, anche la continuazione in bozza è limitata a 720p.

Perché il mio task fallisce quasi all'istante, invece di impiegare il solito tempo di generazione? La causa più comune è che le voci start_video o image_urls non si risolvono effettivamente in un file valido al momento della richiesta — l'API accetta URL sintatticamente corretti senza recuperarli in modo sincrono, quindi un link non raggiungibile si manifesta come uno stato failed rapido, anziché come un errore di validazione preliminare.

Quanto può essere lunga la clip di origine in modalità continuazione? Al massimo 15 secondi e 50MB, in formato MP4. File di origine più lunghi o più grandi non vengono accettati come input start_video.