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

Fonctionnalités et cas d'usage de flux-3-max/text-to-video

flux-3-max/text-to-video est le point de terminaison de génération vidéo à partir de texte sur HiAPI : vous envoyez une invite décrivant une scène, et le modèle renvoie un clip vidéo généré. C'est l'outil approprié lorsque vous disposez d'une idée textuelle plutôt que de médias existants — par exemple une bande-annonce produit, une courte vidéo pour les réseaux sociaux, un aperçu de storyboard ou des plans d'ambiance générés en lot — et que vous souhaitez traiter la génération comme une tâche hébergée plutôt que de l'exécuter vous-même.

Il convient aux flux de travail où la vidéo n'est qu'une étape d'un processus plus large. Un générateur de scripts produit des invites, flux-3-max/text-to-video les transforme en clips vidéo, et votre application se charge de stocker ou de livrer le résultat. Comme l'appel est asynchrone, il convient également aux services backend qui ne peuvent pas maintenir une requête ouverte pendant toute la durée du rendu.

Ne l'utilisez pas lorsque vous avez besoin d'une édition image par image d'une vidéo existante, ni lorsque votre invite n'est en réalité qu'une image statique — pour ce dernier cas, le point de terminaison de génération d'image à partir de texte est moins coûteux et plus rapide. Si la sortie doit réagir à un média fourni, utilisez la variante image-vers-vidéo. Considérez flux-3-max/text-to-video comme le point d'entrée de la génération de clips à partir d'invites, et concevez votre intégration autour de la soumission de tâches plutôt que de réponses synchrones.

Structure de la requête : point de terminaison, authentification et charge utile

Chaque requête vers flux-3-max/text-to-video comporte trois parties : le chemin du point de terminaison, l'en-tête d'authentification et un corps JSON indiquant le modèle et ses entrées.

Authentification

HiAPI utilise un jeton bearer. Placez votre clé API dans l'en-tête Authorization :

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

Gardez la clé côté serveur. Ne l'intégrez pas dans du code client et ne la validez pas dans un dépôt ; chargez-la depuis une variable d'environnement en développement et depuis un gestionnaire de secrets en production.

Identifiant du modèle

Dans le corps de la requête, le champ model sélectionne le point de terminaison. Utilisez l'identifiant exact flux-3-max/text-to-video ; une faute de frappe à cet endroit est la cause la plus fréquente de requête rejetée.

Structure de la charge utile

Le corps minimal contient le nom du modèle et l'invite :

{
  "model": "flux-3-max/text-to-video",
  "prompt": "Au lever du soleil, survol lent au-dessus d'une forêt de pins brumeuse, éclairage cinématographique"
}

Les champs optionnels — durée et interrupteur d'audio natif — sont présentés dans la section suivante. Comme la génération est asynchrone, la réponse immédiate à ce POST est un objet de tâche muni d'un identifiant, que vous devez interroger, plutôt qu'une vidéo terminée. Concevez votre code pour lire d'abord cet identifiant, le reste ensuite.

Contrôler la durée et l'audio natif

Deux contrôles au niveau de la requête déterminent le résultat : la durée du clip vidéo, et si le modèle génère de l'audio en même temps que la vidéo.

Durée

Définissez la longueur du clip avec le champ duration dans la charge utile. Choisissez la durée la plus courte qui raconte l'histoire — les clips courts se rendent plus vite, sont plus faciles à réviser, et vous pouvez toujours en demander un autre. Avant de soumettre, validez la valeur par rapport à la plage documentée de flux-3-max/text-to-video ; une durée hors plage est rejetée à la soumission, et détecter ce problème en local vous épargne un aller-retour.

Audio natif

L'interrupteur d'audio natif détermine si le modèle génère une piste audio avec le clip. Activez-le lorsque la vidéo sera regardée avec du son ; désactivez-le lorsque la vidéo sera muette, sous-titrée ou accompagnée d'une musique ajoutée séparément en post-production. Générer de l'audio que vous allez jeter ne fait qu'augmenter la durée de la tâche sans aucun bénéfice.

Choisir consciemment

Évitez de laisser les valeurs par défaut décider à votre place. Pour une révision rapide de storyboard, un court clip silencieux suffit généralement. Pour un média final destiné aux réseaux sociaux, un clip plus long avec audio natif peut être l'objectif. Encodez ce choix dans la configuration de l'application plutôt que de le coder en dur à l'endroit de l'appel, afin de pouvoir le modifier par fonctionnalité sans toucher au code de la requête. N'envoyez que les champs que vous souhaitez réellement remplacer, et laissez le point de terminaison appliquer ses valeurs par défaut aux autres.

Requête curl utilisable

Le moyen le plus rapide de vérifier vos identifiants et votre charge utile est de soumettre une tâche avec un appel 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": "Un bateau en papier dérive sur une rue trempée par la pluie, lampadaires chaleureux, faible profondeur de champ",
    "duration": 5,
    "native_audio": false
  }'

Définissez d'abord HIAPI_BASE_URL et HIAPI_API_KEY dans votre shell. Les valeurs de durée et d'audio ici ne sont que des exemples — utilisez des valeurs conformes à la plage documentée pour ce modèle.

Lire la réponse immédiate

La réponse est un objet de tâche, non une vidéo. Il contient un job_id (ou identifiant équivalent) ainsi qu'un statut tel que queued ou processing. Conservez cet identifiant ; c'est votre handle pour chaque appel ultérieur. Si la réponse ressemble à un objet d'erreur, vérifiez le code de statut et le message avant de réessayer — une charge utile mal formée échouera de la même manière à chaque fois.

Une soumission réussie signifie seulement que la tâche a été acceptée, rien de plus. Ne cherchez pas d'URL vidéo dans la première réponse ; elle n'y apparaîtra pas avant que la tâche soit terminée.

Gérer le cycle de vie d'une tâche asynchrone

La génération vidéo prend de quelques secondes à quelques minutes, c'est pourquoi HiAPI la modélise sous forme de tâche. Votre client soumet une fois, puis vérifie l'état jusqu'à ce que la tâche atteigne un état terminal.

États

Une tâche passe de queued à processing puis à un état terminal — completed ou failed. Seuls les états terminaux sont définitifs ; tout état intermédiaire signifie qu'il faut continuer d'attendre.

Interroger sans bombarder

Interrogez le point de terminaison d'état avec l'identifiant de tâche que vous avez conservé. Deux règles maintiennent l'interrogation saine :

• Attendez entre les interrogations. Commencez par un court intervalle et augmentez progressivement, ou utilisez un intervalle fixe nettement supérieur au temps d'attente typique en file. Bombarder le point de terminaison d'état n'apporte rien.
• Fixez une limite. Limitez le temps d'attente total et le nombre total de tentatives. Si la tâche n'est pas terminée à ce moment-là, remontez l'information à votre application au lieu de boucler indéfiniment.

Dans un gestionnaire Web, ne bloquez pas le thread de requête sur une boucle d'interrogation. Soumettez, stockez l'identifiant de tâche, renvoyez immédiatement, et laissez un worker en arrière-plan ou le client interroger le cycle de vie. Dans un scénario par lots, une simple boucle avec sleep suffit.

Lire le résultat

Lorsque la tâche est signalée comme completed, la réponse porte une référence de sortie — une URL vidéo ou un handle de média que votre application peut télécharger ou diffuser en streaming. En cas d'échec, lisez le champ error ; il indique généralement la cause (paramètre invalide, refus de contenu, erreur interne). Consignez l'identifiant de tâche avec le message d'échec afin qu'une demande d'assistance ou une nouvelle tentative s'appuie sur des éléments concrets. Ne considérez jamais un champ de sortie manquant comme un succès — vérifiez explicitement l'état.

La même requête en Python

Le flux curl se transpose directement en Python. Un client minimal nécessite une soumission, une boucle d'interrogation et suffisamment de gestion d'erreurs pour distinguer une mauvaise requête d'une tâche lente.

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

Notes d'implémentation

raise_for_status() distingue les erreurs de transport et HTTP (authentification, charge utile mal formée) des échecs au niveau de la tâche, qui apparaissent à l'intérieur d'une réponse réussie. La vérification de failed lit explicitement le champ error plutôt que de supposer que le statut est completed. La limite de tentatives transforme une attente illimitée en exception prévisible.

En production, encapsulez l'interrogation dans une stratégie de retry pour les erreurs réseau transitoires, et réutilisez une seule requests.Session. Si vous exécutez de nombreuses tâches, déplacez wait vers un worker plutôt que dans le chemin de la requête.

Diagnostiquer les échecs courants

La plupart des problèmes d'intégration se rangent dans quelques catégories. Chacune a une méthode de vérification concrète.

Erreurs d'authentification

Un 401 ou 403 signifie que la clé est absente, expirée ou mal formée. Vérifiez que l'en-tête Authorization est présent, qu'il utilise le schéma Bearer, et que la variable d'environnement est réellement renseignée dans l'environnement d'exécution — pas seulement dans votre shell.

Charge utile mal formée

Un 400 signifie généralement que le corps de la requête ne respecte pas le schéma. Vérifiez que le JSON est analysable, que model vaut exactement flux-3-max/text-to-video, et que la requête envoie Content-Type: application/json. Utilisez une bibliothèque JSON pour sérialiser, plutôt que de construire des chaînes à la main.

Valeurs de paramètres invalides

Une durée hors de la plage documentée, un nom de champ inconnu ou un type erroné pour l'interrupteur audio provoquent un rejet à la soumission. Validez localement par rapport aux paramètres documentés du modèle avant d'envoyer.

Interrogation prématurée

Interroger de façon répétée immédiatement après la soumission ne fait pas terminer la tâche plus tôt. Utilisez un backoff ou un intervalle fixe, et laissez l'objet de tâche vous indiquer quand il a dépassé l'état queued.

Échecs de tâche non traités

Une tâche atteignant failed n'est pas nécessairement due à un bug de votre requête — il peut s'agir d'un refus de contenu ou d'une erreur interne. Lisez le message d'erreur, consignez l'identifiant de tâche, et décidez de réessayer avec une invite modifiée ou de remonter le problème.

Prendre la réponse de soumission pour le résultat

Si votre code attend une URL vidéo immédiatement après la soumission, il échouera. La première réponse est une tâche ; seul un état terminal porte la sortie. Une fois ces six vérifications en place, la plupart des problèmes d'intégration sont résolus.