Comment utiliser l'API hiapi pour l'édition vidéo par IA avec flux-3

Ici, « édition » a un sens précis : flux-3 (FLUX.3 Video, de Black Forest Labs) prolonge un clip existant — en continuant son mouvement, son mouvement de caméra et son son, et en générant de nouvelles images — ou construit un plan à partir d'une série ordonnée d'images clés. Il ne découpe pas, ne coupe pas, ne masque pas, n'étalonne pas et ne fait aucun autre traitement sur place des médias existants. Si vous êtes venu chercher un monteur, la FAQ ci-dessous est le moyen le plus rapide de déterminer si flux-3 vous convient réellement avant d'écrire la moindre ligne de code.

Ce qu'il fait vraiment bien : prendre une vidéo que vous possédez déjà et générer une prolongation qui conserve le même sujet, le même langage de caméra et le même son — utile pour rallonger un plan qui se termine trop tôt, ou pour enchaîner plusieurs extraits générés en un plan plus long. L'autre mode prend un ensemble d'images fixes comme images clés ordonnées et génère le mouvement entre elles, ce qui s'apparente à un montage basé sur un story-board, bien qu'aucune vidéo existante n'entre en jeu.

1. Ce dont vous avez besoin

Une clé d'API hiapi (sk-...) récupérable depuis le tableau de bord. flux-3, comme tous les autres modèles hiapi, s'appelle via l'API task unifiée, donc il n'y a ici aucun réglage spécifique au modèle — si vous avez déjà appelé n'importe quel autre modèle vidéo hiapi, vous avez déjà tout ce qu'il faut.

2. Exemple minimal fonctionnel

Créez une tâche, puis interrogez-la (ou utilisez un callback — voir Modèles de production) jusqu'à ce qu'elle atteigne un état terminal.

# 1. Créer la tâche — mode prolongation (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": "继续平移，镜头继续向右漂移，保持相同光照",
      "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. Interroger jusqu'à l'état terminal
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 est une URL HTTPS publique pointant vers un MP4 (la source est limitée à 50 Mo et 15 secondes) — c'est le clip que flux-3 prolonge. duration est un entier de 5 à 20 secondes, qui contrôle la longueur du segment nouvellement généré, et non la longueur de la sortie composée. resolution vaut 720p ou 1080p ; aspect_ratio accepte auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 ou 9:16. generate_audio est un booléen — lorsqu'il vaut true, le son d'ambiance généré par le modèle est directement intégré au MP4 de sortie, et non fourni comme fichier audio séparé. Définissez draft: true pendant l'itération sur le prompt ; les tâches en brouillon coûtent moins cher, mais forcent resolution à 720p (une requête avec à la fois draft: true et resolution: "1080p" est rejetée).

Story-board par images clés (et non édition de médias existants)

L'autre mode d'entrée remplace start_video par image_urls — un tableau ordonné de 1 à 10 URL d'images, que flux-3 traite comme un story-board et génère un mouvement les reliant dans l'ordre :

{
  "model": "flux-3",
  "input": {
    "prompt": "平滑地推轨依次穿过每个场景",
    "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 et start_video sont deux formes de tâche distinctes sur le même modèle — ne les envoyez pas ensemble dans une même requête. Utilisez image_urls lorsque vous construisez un plan à partir de zéro à partir d'images fixes ; utilisez start_video lorsque vous avez déjà des médias générés (ou sources) que vous voulez prolonger.

3. Modèles de production

Utilisez des callbacks plutôt que l'interrogation à grande échelle. Transmettez un objet callback dans le même corps de requête, au lieu d'interroger en boucle :

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

when: "final" ne se déclenche qu'une seule fois, lorsque la tâche atteint un état terminal quelconque — succeeded et failed sont tous deux des états terminaux, donc dédupliquez votre gestionnaire de webhook par taskId, plutôt que de supposer qu'un callback signifie seulement un succès. L'interrogation via GET /v1/tasks/:id convient mieux au débogage local, aux tâches ponctuelles à faible fréquence, ou comme repli de réconciliation si un callback n'arrive pas.

Idempotence. Si vous n'y prenez pas garde, une nouvelle tentative après un délai d'expiration ou une connexion coupée peut créer des tâches dupliquées (et facturables) — conservez l'id de tâche renvoyé par l'appel de création et, avant d'envisager de soumettre une nouvelle tâche, transformez la nouvelle tentative en un GET sur cet id.

Les URL de sortie expirent. Le champ expireAt de chaque entrée de sortie n'est pas décoratif — que vous appreniez le succès de la tâche via un callback ou par interrogation, téléchargez la vidéo et persistez-la dans votre propre stockage dès que la tâche réussit.

Échecs d'authentification. Une clé erronée ou absente renvoie un HTTP 401 avec {"error": {"code": "permission_denied", ...}}. Vérifiez explicitement ce statut/ce code, plutôt que de supposer que tout code non-2xx signifie que la génération elle-même a échoué — « ma clé est fausse » et « le modèle a rejeté mon entrée » nécessitent des corrections différentes.

Validez les URL de médias avant la soumission. start_video et image_urls vérifient le type et le format, mais pas si le fichier à cette URL existe réellement ou est décodable — une URL syntaxiquement valide mais cassée crée quand même une tâche, qui échoue après quelques secondes d'exécution, au lieu d'être rejetée dès la soumission. Avant de brancher des URL dans des tâches par lots, confirmez qu'elles se résolvent bien.

4. Pages associées

• Page du modèle flux-3 — référence complète des paramètres, playground, et tarification actuelle par seconde et par résolution pour les trois modes (texte-vers-vidéo, story-board par images clés et prolongation).
• Documentation sur la création de tâches — référence complète requête/réponse de /v1/tasks, y compris les options de callback.
• Documentation sur l'authentification — comment fonctionnent l'en-tête Authorization: Bearer sk-... et la portée des clés.
• Contrôle des première et dernière images en vidéo IA — une approche connexe, adaptée aux modèles qui interpolent entre deux images fixes, si le mode story-board multi-images clés de flux-3 n'est pas assez précis pour votre plan.
• Tarification hiapi — tarifs actuels (la prolongation coûte plus cher que la génération standard, et le mode brouillon moins cher que les deux — consultez la page en direct plutôt que de coder en dur des chiffres).

5. FAQ

flux-3 peut-il rogner, couper, masquer ou étalonner une vidéo existante ? Non. Le mode « vidéo-vers-vidéo » de flux-3 est la prolongation — il génère de nouvelles images qui prolongent le sujet, le mouvement de caméra et le son du clip source. Il ne modifie pas les images déjà existantes. Aucun modèle hiapi ne propose actuellement d'édition de type montage timeline (rognage/coupe) ni d'édition de zones masquées sur une vidéo.

Quelle différence entre prolongation et story-board par images clés ? La prolongation (start_video) nécessite un fichier vidéo existant et l'étend. Le story-board par images clés (image_urls) ne nécessite que des images fixes et génère le mouvement entre elles — aucune vidéo source. Ce sont des entrées mutuellement exclusives sur le même id de modèle flux-3.

Puis-je utiliser start_video et image_urls dans la même requête ? Non — on choisit un mode par tâche. Envoyer les deux n'est pas une forme d'entrée prise en charge.

draft: true est-il disponible en mode prolongation ? Oui, et c'est le moyen le moins cher d'itérer sur les prompts de prolongation avant de lancer une exécution en pleine résolution — mais, comme en mode standard, la prolongation en brouillon est limitée à 720p.

Pourquoi ma tâche échoue-t-elle presque instantanément, au lieu de prendre le temps de génération habituel ? La cause la plus fréquente est qu'une entrée start_video ou image_urls ne se résout pas réellement en un fichier valide au moment de la requête — l'API accepte les URL syntaxiquement bien formées sans les récupérer de manière synchrone, si bien qu'un lien cassé se manifeste par un état failed rapide, plutôt que par une erreur de validation en amont.

Quelle longueur peut avoir le clip source en mode prolongation ? Au maximum 15 secondes et 50 Mo, au format MP4. Les fichiers sources plus longs ou plus lourds ne sont pas acceptés comme entrée start_video.