Comment appeler flux-3-video via l'API HiAPI : exemples de requêtes curl, Python et réellement exploitables

Ce que flux-3-video propose via l'API

Avant d'écrire la première ligne de code, il est utile de comprendre ce que le modèle flux-3-video peut réellement faire via l'API HiAPI. Cette famille de points de terminaison couvre deux modes d'appel qui partagent la même structure de requête, ainsi qu'une capacité audio optionnelle que vous pouvez activer ou ignorer selon votre cas d'usage.

Les deux modes d'appel

• Texte-vers-vidéo — vous envoyez une invite textuelle et recevez un nouveau clip vidéo généré. Utilisez ce mode lorsque vous n'avez qu'une idée et souhaitez que le modèle génère le mouvement, la composition et le rythme.
• Continuation de vidéo — vous envoyez un clip vidéo existant (ou une référence vers celui-ci) accompagné d'instructions, et le modèle le prolonge. Utilisez ce mode lorsque vous disposez déjà de matière et souhaitez obtenir davantage de contenu sans couture visible.

Audio natif

Le modèle peut également produire de l'audio natif en même temps que la vidéo, contrôlé par des paramètres optionnels dans la même charge utile de requête. Comme ces paramètres sont optionnels, les workflows purement vidéo peuvent totalement les ignorer — il suffit d'omettre les champs audio et la requête se comporte exactement comme en leur absence.

Le modèle mental central sur lequel repose la suite de ce guide est le suivant : il ne s'agit pas de deux API distinctes, ni de deux tutoriels séparés. Ce sont deux formes d'une même requête ; une fois la structure commune comprise, passer de l'une à l'autre ne consiste qu'à remplacer quelques entrées. Tout le reste — identifiants, en-têtes, identifiant de modèle, traitement des réponses — reste inchangé.

Cette conception est intentionnelle. Cela signifie que votre code d'authentification, de gestion des erreurs, de logique de nouvelle tentative et d'analyse des réponses n'est à écrire qu'une fois et se réutilise dans les deux modes ; l'ajout ultérieur de l'audio ne vous obligera pas à tout réécrire.

Authentification, point de terminaison et anatomie de la requête

Chaque appel à flux-3-video suit la même structure. Maîtrisez-la une fois, et les deux modes d'appel deviennent des variantes d'un même thème.

Identifiants

HiAPI authentifie les requêtes à l'aide d'une clé API. Vous la transmettez dans un en-tête, généralement sous forme de bearer token. N'écrivez pas la clé dans le code source — lisez-la depuis une variable d'environnement ou un gestionnaire de secrets, pour qu'elle n'entre jamais dans un système de contrôle de version :

export HIAPI_API_KEY="your-key-here"

Point de terminaison et identifiant de modèle

Les appels sont envoyés à l'URL de base de l'API HiAPI, et la charge utile spécifie explicitement le modèle via l'identifiant flux-3-video. Placer le nom du modèle dans le corps de la requête plutôt que de le coder en dur dans l'URL signifie que le même code client pourra pointer vers un autre modèle plus tard en changeant une seule ligne.

Structure de charge utile commune

Quel que soit le mode, la charge utile est un objet JSON qui contient conceptuellement trois parties :

• Le champ model — toujours flux-3-video.
• Les entrées qui définissent le mode — une invite en texte-vers-vidéo ; un clip source plus une invite en continuation. C'est la seule partie qui change réellement entre les deux modes.
• Les modificateurs optionnels — paramètres audio et autres réglages. Les omettre donne le comportement par défaut.

La pseudo-structure d'une requête est la suivante :

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

C'est tout l'esprit : un identifiant de modèle, un objet input imbriqué qui porte les champs propres au mode, et des clés optionnelles ajoutées uniquement en cas de besoin. Les sections suivantes détaillent chaque mode.

Texte-vers-vidéo : votre première requête curl exploitable

Voici une requête minimale mais complète pour générer un clip vidéo à partir d'une invite. Elle suppose que HIAPI_API_KEY est déjà exportée dans votre 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"
    }
  }'

Le rôle de chaque champ

• Authorization — porte votre bearer token. Sans lui, la requête est rejetée avant même que la génération ne commence.
• Content-Type: application/json — le corps de la requête est du JSON, alors déclarez-le ; l'oublier est une cause fréquente de réponses 4xx déroutantes.
• model — identifie flux-3-video comme modèle cible.
• input.prompt — la seule entrée créative obligatoire en mode texte-vers-vidéo. Rédigez-la comme une description de plan : sujet, mouvement, composition, lumière, ambiance.

Points clés pour rédiger des invites qui valent l'effort

Comme l'invite est le seul levier créatif dans ce mode, sa qualité détermine directement le résultat. Deux habitudes aident :

• Décrivez le mouvement, pas seulement le contenu. « A dolly shot through… » (un travelling avant à travers…) donne au modèle un comportement de caméra à animer ; une description statique ne lui laisse rien à exploiter.
• Restez concret. Des indices précis de lumière et de matière (« wet asphalt », « neon reflections ») produisent souvent des images plus cohérentes que des adjectifs abstraits.

Après avoir exécuté cette requête et examiné la réponse, vous avez validé la clé, les en-têtes et la charge utile de base — le fondement de tout le reste.

Continuation de vidéo : prolonger un clip existant

La continuation réutilise la structure de la section précédente, mais la forme de l'objet input change. L'invite n'existe plus seule ; elle est associée au clip source que le modèle doit prolonger.

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

Ce qui change par rapport au texte-vers-vidéo

• Une entrée vidéo apparaît. Vous fournissez le clip existant sur lequel le modèle doit construire. C'est la différence décisive entre les deux modes.
• L'invite devient directive, et non générative. En texte-vers-vidéo, vous décrivez toute la scène ; ici, vous décrivez ce qui se passe ensuite. Rédigez-la comme une instruction de continuation : où va la caméra, ce qui entre dans le cadre, comment la scène évolue.
• Tout le reste est identique. Même point de terminaison, mêmes en-têtes, même identifiant de modèle, même enveloppe input. Votre code client n'a besoin de se ramifier qu'au moment de construire la charge utile.

Maintenir la cohérence à la jonction

Le modèle doit correspondre à l'apparence du clip source pour éviter une coupure visible. Des instructions courtes et précises qui préservent le style existant fonctionnent souvent mieux que de longues descriptions qui réinventent la scène. Si la première continuation dérive, rapprochez l'invite du contenu réel du clip source plutôt que d'ajouter davantage de détails ailleurs.

Note sur la référence de clip

La convention d'entrée exacte pour le clip source est définie par le schéma d'entrée du modèle sur HiAPI. Suivez ce schéma plutôt que de deviner le format des champs — c'est la source d'autorité sur ce que la continuation accepte comme entrée.

Ajouter les paramètres audio natifs

L'audio natif est précisément là où le modèle des modificateurs optionnels prend toute sa valeur. Les paramètres audio se trouvent dans le même objet input que les autres champs, et comme ils sont optionnels, les requêtes des deux sections précédentes restent valides sans eux.

Où ils se trouvent

Les réglages audio appartiennent à l'intérieur de input, aux côtés de prompt et (en mode continuation) de video. Conceptuellement :

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

Protéger les workflows purement vidéo

La discipline importante ici est simple : traitez le bloc audio comme purement additif.

• Ne mettez pas explicitement les champs audio à une valeur « désactivé » — omettez-les. L'absence du bloc est plus propre qu'une désactivation explicite et risque moins d'entrer en conflit avec de futures évolutions du schéma.
• Construisez la charge utile de manière incrémentale. Partez du corps de requête minimal et n'ajoutez la clé audio que dans les chemins de code où l'utilisateur demande réellement l'audio. Cela maintient votre chemin par défaut exactement identique aux exemples purement vidéo.
• Avant de brancher l'audio en production, consultez le schéma pour confirmer les noms exacts des indicateurs et les valeurs acceptées. Le nommage des paramètres est défini par le schéma d'entrée du modèle sur HiAPI ; le nom de bloc ci-dessus ne montre que l'emplacement, il ne garantit pas l'orthographe des champs.

Quand l'activer

Activez l'audio lorsque le livrable est un clip vidéo fini et autonome — contenu pour réseaux sociaux, démonstrations, courtes œuvres narratives. Laissez-le désactivé lorsque vous superposerez en aval votre propre musique ou narration ; générer de l'audio que vous finirez par jeter gaspille des ressources de calcul dans le pipeline.

Comme l'audio est embarqué dans la même charge utile que tout le reste, il n'y a pas d'appel séparé, pas de second jeu d'identifiants, et aucun branchement supplémentaire de traitement des réponses à maintenir, hormis la lecture de ce que la réponse renvoie.

Écrire la même requête en Python

Transcrire l'appel curl en Python est mécanique, car la structure de la requête est identique. L'exemple ci-dessous n'utilise que la bibliothèque standard, il fonctionne donc dans n'importe quel environnement ; si vous préférez requests ou httpx, la structure se transpose directement.

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)

Pourquoi cette organisation

• Une fonction, deux modes. Le paramètre video est optionnel ; lorsqu'il vaut None, la fonction génère une requête texte-vers-vidéo. Lorsqu'il est défini, la même fonction génère une requête de continuation. Pas de client séparé, pas d'en-têtes dupliqués.
• L'audio doit être explicitement activé. L'indicateur audio vaut False par défaut, donc le bloc audio n'est jamais ajouté sauf demande explicite — c'est exactement le modèle décrit plus haut.
• La clé vient de l'environnement. La clé API est lue depuis HIAPI_API_KEY et n'est jamais codée en dur.

Pour l'adapter, remplacez simplement les appels print par l'action requise par votre pipeline — écrire la réponse dans un manifeste, mettre en file des tâches suivantes ou notifier une file d'attente. La logique de requête elle-même n'a pas besoin de changer.

Dépannage et liste de contrôle pour la production

Lorsqu'un appel échoue, parcourez la liste suivante dans l'ordre — elle couvre la grande majorité des problèmes.

Liste de diagnostic

• 401 ou erreur d'authentification — HIAPI_API_KEY est-elle réellement exportée dans le shell ou le processus qui exécute le code ? Une clé définie dans un terminal ne se transmet pas à une tâche cron.
• 415 ou erreur d'analyse inattendue — Content-Type: application/json est-il présent ? L'oublier est l'échec silencieux le plus typique.
• Un appel de continuation renvoie 4xx — votre charge utile contient-elle le clip source dans la forme attendue par le schéma d'entrée du modèle ? Une référence de clip mal formée échoue avant même que la génération ne commence.
• Audio absent de la sortie — le bloc audio est-il réellement inclus dans la charge utile ? En débogage, journalisez le corps de requête sérialisé ; construire un dictionnaire puis oublier d'attacher la clé arrive facilement.
• input vide ou tronqué — imprimez le JSON exact que vous envoyez réellement. Presque tous les échecs « étranges » se résolvent une fois qu'on voit de ses yeux le corps de requête transmis sur le réseau.

Avant la mise en production

• Ne codez jamais les clés en dur. Utilisez toujours des variables d'environnement ou un gestionnaire de secrets.
• Journalisez à la fois le corps de requête et le corps de réponse, au moins dans l'environnement de préproduction. Reproduire un échec sans la charge utile exacte relève de la devinette.
• Traitez les champs optionnels comme optionnels. Construisez la charge utile de manière incrémentale — d'abord le corps minimal, puis ajoutez video, enfin audio uniquement si nécessaire. Cela garde votre chemin par défaut aligné sur les exemples de la documentation.
• Gardez la sélection du mode explicitement visible dans votre propre code. Une fonction avec un paramètre video optionnel convient ; un booléen enfoui à trois niveaux de profondeur, non.
• Chaque fois que vous ajoutez un champ, consultez à nouveau le schéma d'entrée du modèle sur HiAPI. C'est la référence d'autorité pour les noms de paramètres et les formats acceptés, et elle sera plus à jour que n'importe quel tutoriel.

Le point essentiel mérite d'être répété : le texte-vers-vidéo, la continuation et l'audio natif sont trois variantes d'une même forme de requête. Maîtrisez la structure une fois, et chaque nouvelle capacité n'est qu'un ajout, pas une réécriture. Bon développement.