Générer des vidéos courtes en lot avec hailuo-2.3-fast/image-to-video sur hiapi

Le succès d'une vidéo courte dépend de la vitesse d'itération. Si votre workflow est une chaîne de production orientée TikTok ou Reels, vous n'avez pas besoin d'une sortie 4K de niveau cinéma — vous avez besoin d'un modèle capable de transformer une image produit statique en un clip exploitable en moins d'une minute, et à un coût suffisamment bas pour lancer des dizaines de variantes avant de choisir la meilleure. C'est exactement le positionnement de hailuo-2.3-fast/image-to-video : le frère du niveau Fast de hailuo-2.3, dont la tarification et le réglage sont spécifiquement pensés pour les workflows à haut volume et à tentatives multiples jetables.

Ce guide vous montre comment l'utiliser comme moteur de vidéos courtes en lot : comment choisir les images sources, comment le piloter via l'API de tâches asynchrones, comment valider les détails de schéma qui, sans cela, vous vaudront des erreurs 400, et comment raisonner sur l'économie de son exploitation à l'échelle TikTok/Reels.

Ce que le modèle vous apporte

hailuo-2.3-fast/image-to-video prend une image statique et un prompt, et les anime en un court clip vidéo. Il se trouve sur la page du modèle hailuo-2.3-fast/image-to-video et — comme tous les modèles sur hiapi — s'appelle via le point de terminaison asynchrone unifié /v1/tasks : vous POSTez une tâche, vous interrogez (ou enregistrez un callback) jusqu'à l'achèvement, puis vous récupérez la vidéo depuis une URL de sortie à durée de vie courte.

Vérifié contre l'API en ligne au moment de la rédaction :

• Entrée : une image (image_url) + un prompt textuel décrivant le mouvement souhaité
• Sortie : MP4, durée fixe de 6s ou 10s (pas de longueur arbitraire)
• Tarification : prix forfaitaire par vidéo, pas de facturation à la seconde — 0,27 $ pour un clip de 6 secondes, 0,46 $ pour un clip de 10 secondes
• Temps de traitement : notre clip de test s'est terminé de bout en bout (soumission → succès) en environ 80 secondes

Le prix forfaitaire par vidéo est le détail crucial pour les traitements par lots : une tentative de 6 secondes coûte le même prix, que votre prompt atteigne le mouvement visé du premier coup ou que vous en soyez à la quatrième tentative. Au tarif du niveau Fast, lancer 5 à 6 variantes sur la même image clé pour trouver celle dont le mouvement est le plus fluide coûte encore moins cher que la plupart des modèles vidéo haut de gamme pour une seule tentative. Avant de budgétiser un lot, vérifiez les chiffres actuels sur la page de tarification — les prix évoluent.

Si vous avez besoin de la référence complète des paramètres, d'options de durée plus longues ou d'une comparaison côte à côte avec le niveau hailuo-2.3 non Fast, consultez notre tutoriel d'intégration de l'API hailuo-2.3-fast/image-to-video — ce guide se concentre sur l'angle lot/workflow, plutôt que sur la référence brute de l'API.

Workflow : image statique → clip court

Le principe de la vidéo courte est simple : partir d'une image statique que vous possédez déjà (photo produit, hero shot généré, visuel de marque) et laisser le modèle ajouter du mouvement — un léger travelling avant, une rotation subtile, une ambiance flottante — plutôt que de générer une vidéo à partir de zéro. Cela verrouille votre identité visuelle (même produit, même éclairage, même composition) tout en produisant un contenu qui n'est pas une simple publication statique.

Voici un cas réel : une image statique verticale (9:16) d'une basket posée sur un socle éclairé, pilotée par un prompt de mouvement décrivant un travelling avant lent et une rotation douce.

L'image source et la requête complète :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Slow smooth push-in on a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating above a wet concrete pedestal, subtle rotation revealing the side panel, mist drifting through teal-to-amber rim light, dust particles catching the light, stable cinematic camera movement, premium commercial product-video finish",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Réponse :

{"code":200,"data":{"taskId":"tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X"},"message":"success"}

Interrogez jusqu'à ce que le traitement soit terminé :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X \
  -H "Authorization: Bearer $HIAPI_API_KEY"

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

Ce output[0].url est temporaire — téléchargez-le immédiatement et archivez-le dans votre propre stockage. Ne le liez pas à chaud et ne le stockez pas dans un champ de base de données en comptant sur une URL stable.

Schéma d'entrée (vérifié contre l'API en ligne)

Le schéma de ce modèle est bien plus restreint que ce que vous attendez des autres modèles vidéo de la plateforme — pas de contrôle du ratio d'image, pas de niveaux de résolution, pas de seed.

Champ	Type	Contrainte	Obligatoire
prompt	string	décrit le mouvement/la scène	Oui
image_url	string	au singulier — une URL publique, pas un tableau	Oui
duration	string	énumération "6" ou "10" — en tant que chaîne, pas un nombre	Oui
prompt_optimizer	boolean	autorise la plateforme à réécrire/améliorer votre prompt	Non

Deux pièges vous vaudront des 400 si vous transposez les hypothèses d'autres modèles :

1. image_url est au singulier, pas image_urls. Plusieurs autres modèles i2v sur hiapi acceptent un tableau d'images de référence ; ce modèle n'en accepte qu'une. Envoyer un tableau vous donnera une erreur de champ manquant, pas une conversion de type utile.
2. duration doit être la chaîne "6" ou "10", pas le nombre 6. Envoyer le nombre 6 renvoie duration: got number, want string. Et aucune valeur hors de cette énumération à deux valeurs n'est acceptée — ce niveau n'offre pas de contrôle de durée arbitraire.

Envoyer aspect_ratio, resolution, seed ou watermark — champs courants sur les modèles frères — est directement rejeté avec additional properties ... not allowed. Le modèle hérite du ratio d'image de l'image d'entrée, donc si vous avez besoin d'une sortie 9:16 pour Reels/TikTok, recadrez ou générez votre image source en 9:16 avant la soumission (c'est précisément ce que nous avons fait pour l'image de basket ci-dessus).

Python de bout en bout

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

Pour un véritable traitement par lots — par exemple tester 6 variantes de prompt sur la même image source afin de choisir le mouvement le plus fluide — encapsulez cette fonction dans une boucle sur votre liste de prompts et vérifiez chaque task_id indépendamment, plutôt que de bloquer séquentiellement ; à environ 80 secondes par clip, c'est le traitement en parallèle de plusieurs tâches qui donne vraiment l'impression de vitesse au niveau Fast.

Questions fréquentes

Puis-je contrôler le ratio d'image de la sortie ? Non — ce modèle n'a pas de champ aspect_ratio, et l'envoyer renvoie une 400. La sortie suit le ratio d'image de l'image d'entrée, donc préparez votre image source au ratio souhaité avant la soumission (9:16 pour Reels/TikTok, 1:1 pour les publications de flux).

Pourquoi ma requête échoue-t-elle avec "got number, want string" ? Vous avez envoyé duration comme nombre JSON. Il doit être la chaîne "6" ou "10" — ce sont les deux seules valeurs valides.

Est-ce le même modèle que hailuo-2.3/image-to-video (non Fast) ? Non — le niveau Fast est un modèle distinct sur hiapi, tarifé séparément, avec son propre schéma, ajusté pour la vitesse et le coût plutôt que pour le niveau standard. Si vous avez besoin d'une présentation de référence non orientée lot, consultez le tutoriel d'intégration complet.

Puis-je lui fournir des images générées plutôt que de vraies photos ? Oui — l'image source peut provenir de n'importe quel modèle d'image sur hiapi (ou ailleurs), tant qu'il s'agit d'une URL accessible publiquement. Utiliser les images statiques que vous produisez déjà pour d'autres formats (visuels produit, affiches) est généralement le moyen le plus rapide d'obtenir une vidéo courte, sans processus créatif séparé.

Le prix varie-t-il avec la résolution ? Ce modèle n'a pas de paramètre de résolution, donc le prix est forfaitaire selon la durée, quelle que soit la résolution de l'image d'entrée — au moment de la rédaction, 0,27 $ pour 6s et 0,46 $ pour 10s. Vérifiez sur la page de tarification.

Points clés

• hailuo-2.3-fast/image-to-video transforme une image statique en MP4 de 6s ou 10s, à prix forfaitaire par vidéo (0,27 $ / 0,46 $) plutôt qu'à la seconde — assez bon marché pour lancer plusieurs variantes de prompt sur chaque image source.
• Le schéma est volontairement restreint : prompt, image_url (au singulier), duration (énumération de chaînes "6"/"10"), et le champ optionnel prompt_optimizer — pas de contrôle du ratio d'image, de la résolution ni du seed.
• La sortie hérite du ratio d'image de l'image d'entrée, donc préparez votre image source en 9:16 (ou tout ratio requis par votre plateforme) avant la soumission.
• Les deux erreurs d'intégration les plus fréquentes sont l'envoi de image_url sous forme de tableau et l'envoi de duration sous forme de nombre plutôt que de chaîne.
• Pour les workflows de vidéos courtes en lot, le prix forfaitaire par vidéo et un temps de traitement d'environ 80 secondes rendent viable la génération de plusieurs tentatives avec sélection du meilleur mouvement, plutôt qu'une seule soumission par élément.

Prêt à l'essayer sur vos propres visuels produit ? Rendez-vous sur la page du modèle hailuo-2.3-fast/image-to-video pour tester une requête directement, ou si vous souhaitez d'abord comparer le niveau Fast aux autres options image-vers-vidéo, consultez le catalogue complet des modèles.