Comment appeler flux-3-max/keyframes-to-video via l'API HiAPI : guide curl et Python

Ce que fait réellement cette intégration

flux-3-max/keyframes-to-video est une API de tâches asynchrones destinée à générer une vidéo à partir d'images clés. Contrairement aux points de terminaison synchrones qui renvoient le résultat dans la même réponse HTTP, ce modèle reçoit vos images clés, crée une tâche en arrière-plan et renvoie un identifiant de tâche permettant de suivre l'avancement.

Le cycle de vie de bout en bout se décompose en quatre phases :

1. Authentification — chaque requête transportando votre clé API HiAPI.
2. Soumission — envoi des images clés и des paramètres pour lancer la tâche vidéo.
3. Interrogation — consultation répétée de l'état de la tâche jusqu'à atteindre un état final.
4. Récupération — téléchargement de la vidéo générée depuis l'URL renvoyée lorsque la tâche réussit.

Garder ce cycle de vie en tête détermine la façon dont vous écrivez votre client : la soumission et la récupération du résultat sont des appels distincts, и votre application doit tolérer une tâche qui prend de dizaines de secondes à plusieurs minutes. Les exemples curl et Python ci-dessous suivent ces quatre mêmes phases, afin que vous puissiez porter ce flux dans n'importe quel langage ou exécuteur de tâches.

Obtenir une clé API et s'authentifier

Votre clé API est émise depuis le tableau de bord HiAPI. Traitez-la comme un mot de passe : elle identifie votre compte et autorise les appels facturés, elle ne doit donc jamais apparaître dans le code source, l'historique de commits ou les logs.

L'authentification est transmise dans un en-tête HTTP à chaque requête :

Authorization: Bearer $HIAPI_API_KEY

En pratique, stockez la clé dans une variable d'environnement et lisez-la à l'exécution. Pour les exemples shell, exportez-la une fois par session :

export HIAPI_API_KEY="your-key-here"

En Python, lisez-la via os.environ["HIAPI_API_KEY"] plutôt que de coder la chaîne en dur. Ajoutez le fichier .env à .gitignore, et si vous journalisez les requêtes pour déboguer, masquez l'en-tête Authorization avant qu'il n'atteigne l'agrégateur de logs. Si une clé a été exposée, faites-la tourner immédiatement depuis le tableau de bord.

Construire la requête avec curl

Soumettre une tâche vidéo consiste à envoyer un corps JSON qui spécifie le modèle et transporte vos images clés. Les noms de champs exacts pour l'entrée des images clés et les paramètres de génération sont documentés sur la page du modèle ; considérez-la comme la source de référence. La structure ci-dessous illustre la forme de la requête.

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"
      ]
    }
  }'

Rôle de chaque partie :

• model — sélectionne flux-3-max/keyframes-to-video, afin que le même point de terminaison puisse ensuite router vers d'autres modèles sans modifier votre code de transport.
• input.keyframes — liste ordonnée d'URL d'images. L'ordre compte : la première image ancre le début du clip, les images suivantes guident les moments suivants.
• Authorization — l'en-tête bearer décrit ci-dessus.
• Content-Type — requis pour un corps JSON.

La réponse est un objet tâche contenant un identifiant. Conservez cet ID ; c'est le handle de toutes les interrogations suivantes.

La même requête en Python

La version Python reprend l'appel curl. Utiliser requests permet de rester concis, mais la bibliothèque standard convient tout aussi bien si vous souhaitez zéro dépendance.

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)

Deux détails méritent d'être conservés : le timeout explicite, pour qu'une connexion bloquée ne fige pas indéfiniment votre processus worker ; et raise_for_status(), pour qu'un 4xx ou 5xx remonte comme une exception plutôt que comme une charge d'erreur silencieuse. Gardez la fonction courte et pure — elle doit soumettre et renvoyer l'ID, rien de plus. L'interrogation est une autre affaire.

Interroger l'état de la tâche et récupérer le résultat

La génération vidéo demande un temps de calcul réel, l'API ne bloque donc pas jusqu'à l'apparition du fichier. À la place, vous interrogez la tâche jusqu'à son achèvement. L'état succeeded porte l'URL de sortie ; failed porte l'erreur ; toute autre valeur signifie qu'il faut continuer d'attendre.

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")

Notes de conception pour la production :

• Intervalle d'interrogation — quelques secondes suffisent. Marteler le point de terminaison ajoute de la charge sans accélérer la tâche.
• Échéance — limitez toujours le temps d'attente total et signalez l'échec bruyamment plutôt que de boucler indéfiniment.
• Téléchargement — l'URL renvoyée est temporaire ; récupérez le fichier immédiatement après la réussite de la tâche et déplacez-le vers votre propre stockage.
• Découplage — dans une application web, exécutez cette boucle dans un processus worker en arrière-plan et notifiez le client via un webhook ou une file d'attente, plutôt que de garder la requête HTTP ouverte.

Gérer les erreurs et les cas limites

La plupart des échecs d'intégration se rangent en quatre catégories.

Erreurs d'authentification (401/403). Clé absente, mal formée ou plus valide. Vérifiez que la variable d'environnement est bien exportée dans le processus qui effectue l'appel — un piège fréquent : le shell local fonctionne, mais la variable manque dans le conteneur ou la tâche cron.

Erreurs d'entrée (4xx). Une URL d'image clé inaccessible, un format d'image non pris en charge ou des paramètres hors de la plage autorisée feront rejeter la soumission. Validez que chaque URL d'image clé est accessible publiquement avant de soumettre ; les hôtes lents ou restreints sont la cause la plus fréquente d'échec d'une requête par ailleurs correcte.

Échecs de tâche. Une tâche peut être acceptée puis échouer pendant la génération. Vérifiez toujours le champ d'erreur au lieu de considérer une interrogation terminée comme un succès. Journalisez l'ID de tâche avec l'erreur afin de pouvoir la rattacher à une demande de support.

Délais d'attente et nouvelles tentatives. Une erreur réseau à la soumission peut généralement être réessayée sans risque avec un backoff. Réessayer après une soumission réussie ne l'est pas — vous risquez de créer des tâches en double et d'engendrer des frais en double. Lisez la réponse avant de réessayer, et utilisez également un backoff exponentiel avec jitter dans la boucle d'interrogation.

Un dernier réflexe d'hygiène : ne journalisez jamais l'en-tête Authorization, et si les URL d'images clés contiennent des chaînes de requête signées, nettoyez-les. En cas de doute sur les noms de champs ou les limites de ce modèle, consultez la documentation flux-3-max/keyframes-to-video et reprenez ces valeurs à l'identique dans votre client.