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

Cosa fa realmente questa integrazione

flux-3-max/keyframes-to-video è un'API asincrona basata su attività per generare video a partire da immagini keyframe. A differenza degli endpoint sincroni che restituiscono il risultato nella stessa risposta HTTP, questo modello riceve i tuoi keyframe, crea un'attività in background e restituisce un identificatore di attività che puoi usare per controllare l'avanzamento.

Il ciclo di vita end-to-end si articola in quattro fasi:

1. Autenticazione — ogni richiesta trasporta la tua chiave API HiAPI.
2. Invio — inviare i keyframe e i parametri per avviare l'attività video.
3. Polling — interrogare ripetutamente lo stato dell'attività finché non raggiunge uno stato terminale.
4. Recupero — scaricare il video generato dall'URL restituito quando l'attività riesce.

Tener presente questo ciclo di vita determina come scrivi il client: l'invio e il recupero del risultato sono chiamate separate, e la tua applicazione deve tollerare un'attività che può richiedere da decine di secondi a diversi minuti. Gli esempi curl e Python che seguono rispettano le stesse quattro fasi, così puoi trasferire questo flusso in qualsiasi linguaggio o runner di job.

Ottenere la chiave API e autenticarsi

La tua chiave API viene emessa dalla dashboard HiAPI. Trattala come una password: identifica il tuo account e autorizza le chiamate fatturate, quindi non deve mai comparire nel codice sorgente, nella cronologia dei commit o nell'output dei log.

L'autenticazione viene trasmessa in ogni richiesta tramite un header HTTP:

Authorization: Bearer $HIAPI_API_KEY

In pratica, conserva la chiave in una variabile d'ambiente e leggila a runtime. Per gli esempi shell, esportala una volta per sessione:

export HIAPI_API_KEY="your-key-here"

Per Python, leggila tramite os.environ["HIAPI_API_KEY"] invece di scrivere la stringa nel codice. Aggiungi il file .env a .gitignore e, se registri le richieste per il debug, oscura l'header Authorization prima che raggiunga l'aggregatore di log. Se la chiave viene esposta, ruotala immediatamente dalla dashboard.

Costruire la richiesta con curl

Inviare un'attività video significa inviare un corpo JSON che specifica il modello e trasporta i tuoi keyframe. I nomi esatti dei campi per l'input dei keyframe e per i parametri di generazione sono documentati nella pagina del modello, quindi usala come fonte autorevole; la struttura seguente mostra la forma della richiesta.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

Il ruolo di ciascuna parte:

• model — seleziona flux-3-max/keyframes-to-video, così lo stesso endpoint può in futuro instradare verso altri modelli senza modificare il tuo codice di trasporto.
• input.keyframes — elenco ordinato di URL di immagini. L'ordine conta: il primo frame ancora l'inizio della clip, i frame successivi guidano i momenti seguenti.
• Authorization — l'header bearer descritto sopra.
• Content-Type — necessario per il corpo JSON.

La risposta è un oggetto attività contenente un identificatore. Salva quell'ID; è il riferimento per ogni polling successivo.

La stessa richiesta in Python

La versione Python rispecchia la chiamata curl. Usare requests mantiene il codice breve, ma se preferisci zero dipendenze anche la libreria standard va bene.

import os
import requests

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


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

Due dettagli da mantenere: il timeout esplicito, così le connessioni in sospeso non bloccano all'infinito il tuo worker; e raise_for_status(), così un 4xx o un 5xx emerge come eccezione anziché come payload di errore silenzioso. Mantieni la funzione piccola e pura — deve inviare e restituire l'ID, nient'altro. Il polling è un'altra cosa.

Eseguire il polling dello stato dell'attività e recuperare i risultati

La generazione video richiede tempo di calcolo reale, quindi l'API non si blocca finché il file non è disponibile. Invece, interroghi l'attività finché non è completata. Lo stato succeeded trasporta l'URL dell'output; failed trasporta l'errore; qualsiasi altro valore significa che devi continuare ad attendere.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

Note di progettazione per la produzione:

• Intervallo di polling — pochi secondi sono sufficienti. Bombardare l'endpoint aumenta il carico ma non fa completare l'attività più velocemente.
• Scadenza — limita sempre il tempo totale di attesa e segnala l'errore in modo esplicito in caso di fallimento, invece di ciclare all'infinito.
• Download — l'URL restituito è temporaneo; recupera il file immediatamente dopo il successo dell'attività e spostalo nel tuo storage.
• Disaccoppiamento — in un'applicazione web, esegui questo ciclo in un worker in background e notifica il client tramite webhook o coda, invece di mantenere aperta la richiesta HTTP.

Gestire errori e casi limite

La maggior parte dei fallimenti di integrazione rientra in quattro categorie.

Errori di autenticazione (401/403). Chiave mancante, malformata o non più valida. Verifica che la variabile d'ambiente sia effettivamente esportata nel processo che effettua la chiamata — un errore comune è che la shell locale funziona ma la variabile manca nel container o nel job cron.

Errori di input (4xx). URL di keyframe non raggiungibili, formati di immagine non supportati o parametri fuori dall'intervallo consentito causano il rifiuto dell'invio. Prima di inviare, verifica che ogni URL di keyframe sia accessibile pubblicamente; host lenti o limitati sono la causa più frequente di fallimento di richieste altrimenti corrette.

Fallimenti dell'attività. Un'attività può essere accettata e poi fallire durante la generazione. Controlla sempre il campo dell'errore, invece di considerare riuscito un polling completato. Registra l'ID dell'attività insieme all'errore, così puoi correlarlo a una richiesta di supporto.

Timeout e retry. Gli errori di rete in fase di invio sono di solito sicuri da ritentare con backoff. Ritentare dopo un invio riuscito non lo è — potresti creare attività duplicate e sostenere costi duplicati. Leggi la risposta prima di ritentare e usa un backoff esponenziale con jitter anche nel ciclo di polling.

Un'ultima nota di igiene: non registrare mai l'header Authorization e, se gli URL dei keyframe contengono stringhe di query firmate, ripuliscile. In caso di dubbi sui nomi dei campi o sui limiti di questo modello, consulta la documentazione di flux-3-max/keyframes-to-video e riproduci quei valori esattamente nel tuo client.