Blog

Tutoriel

Comment appeler hailuo-2.3/image-to-video via l'API HiAPI : curl et Python

Nov 12, 2026
Image de couverture : de larges bandes de tissu entrecroisées sur un fond brun café foncé, dans un style d'illustration de tissage à plat, agrémentées de petits carrés couleur laiton.
Sur cette page

Ce que fait hailuo-2.3/image-to-video, et quand l'utiliser

hailuo-2.3/image-to-video est un modèle image-vers-vidéo proposé via l'API unifiée de HiAPI. Vous lui fournissez une image statique comme première image, puis un prompt décrivant comment la scène doit bouger ; le modèle génère une courte vidéo qui démarre à partir de cette image et déroule l'animation à partir de là.

Le mot-clé est première image. En texte-vers-vidéo, le modèle imagine la scène entière à partir du prompt ; en image-vers-vidéo, il ancre la composition, le sujet, l'éclairage et le style sur l'image fournie. C'est donc le bon choix lorsque vous disposez déjà d'un visuel précis à conserver — photo produit, référence de personnage, image de storyboard, rendu conceptuel — et que vous souhaitez y ajouter du mouvement plutôt que de le réinventer.

Cas d'usage adaptés à cet endpoint :

  • Vous devez rester cohérent avec des éléments existants. Une photo produit ne doit pas être régénérée en une version légèrement différente : elle doit s'animer.
  • Vous construisez un storyboard ou un animatique à partir d'images fixes et voulez prévisualiser rapidement le mouvement.
  • Vous avez besoin d'une composition contrôlée : le cadrage et la position du sujet viennent de l'image, le prompt ne décrit que le mouvement.

Si vous n'avez pas d'image de référence et souhaitez que le modèle conçoive le plan, ou si les détails visuels se prêtent mieux à une description textuelle qu'à une image fixe, le texte-vers-vidéo est plus adapté.

Prérequis et obtention de la clé API

Avant la première requête, il vous faut trois choses : un compte HiAPI, une clé API et une URL d'image de première image accessible publiquement.

Compte et clé API

Connectez-vous à HiAPI et créez une clé API dans la console. Traitez la clé comme un secret : conservez-la dans une variable d'environnement plutôt que de la coller dans un fichier source. Les exemples de ce guide lisent tous HIAPI_API_KEY.

export HIAPI_API_KEY="your-api-key-here"

URL d'image accessible

L'image transmise comme première image doit être récupérable par le serveur : une URL de stockage cloud signée, un lien CDN ou toute URL HTTPS publique convient, mais pas un chemin de fichier local. Si votre ressource se trouve derrière une authentification, générez une URL signée à durée limitée pour la requête.

Avant d'automatiser quoi que ce soit, vérifiez le chemin d'endpoint, les noms de paramètres et les valeurs autorisées actuels dans la documentation de référence de l'API HiAPI la plus récente. Les interfaces des modèles évoluent, et coder en dur des noms de paramètres vus dans d'anciens tutoriels est une source d'erreur courante et évitable. Les tarifs actuels et les éventuelles règles de quota figurent dans le panneau tarifaire du site — vérifiez-y, ne supposez rien.

Structure de la requête : entrée image et paramètres

Conceptuellement, une requête image-vers-vidéo comporte trois parties : l'identifiant du modèle, l'image et les paramètres de génération.

Identifiant du modèle

Chaque appel cible hailuo-2.3/image-to-video. Centralisez-le à un seul endroit dans votre code, afin qu'un changement de modèle ne demande qu'une modification d'une ligne.

Image de première image

C'est l'URL de l'image statique de départ de la vidéo. Son ratio d'aspect et sa résolution déterminent la géométrie de base de la sortie : choisissez donc une image qui possède déjà la composition voulue, plutôt que de la recadrer après coup. Une image propre, bien éclairée et au sujet clair produit un mouvement bien plus prévisible qu'un collage encombré.

Prompt

Le champ texte qui décrit le mouvement — présenté dans la section suivante.

Durée et résolution

Les tâches image-vers-vidéo proposent généralement des options de longueur de clip et de résolution de sortie. Ces paramètres sont les plus susceptibles de changer selon la version du modèle : ne les codez donc pas en dur de mémoire. Ouvrez la documentation de référence de l'API la plus récente, lisez les noms de champs acceptés et les valeurs autorisées, et placez ces valeurs dans un objet de configuration plutôt que d'éparpiller des littéraux dans le code. Si une valeur est rejetée, la réponse de l'API indique généralement quel champ pose problème.

Le corps de la requête est du JSON ; la réponse renvoie un identifiant de tâche, pas la vidéo terminée, ce qui est abordé dans la section sur le polling ci-dessous.

Rédiger des prompts qui produisent un mouvement crédible

L'image décrit déjà ce qu'il y a dans la scène. Le rôle du prompt est de décrire comment cela bouge. Un prompt qui redécrit le sujet gaspille les capacités du modèle ; un prompt qui précise le mouvement, le comportement de la caméra et la physique produit des clips bien meilleurs.

Décrire le mouvement, pas le contenu

Mauvais exemple : « Une femme en manteau rouge se tient debout sur un pont. »

Meilleur exemple : « La femme tourne lentement la tête vers la caméra, son manteau flotte au vent ; la caméra avance doucement. »

Séparer le mouvement du sujet et le mouvement de caméra

Soyez explicite sur les deux. « Travelling avant lent », « dérive caméra à l'épaule », « plan fixe » et « orbite vers la droite » indiquent au modèle comment l'image elle-même change ; « les cheveux flottent », « la vapeur s'élève » et « les pages tournent » décrivent ce qui se passe à l'intérieur du cadre. Combiner les deux produit un plan cohérent plutôt qu'une image qui dérive.

Respecter la physique

Exigez des mouvements plausibles à des vitesses plausibles : « le tissu ondule légèrement », « l'eau s'écoule vers l'aval », « la fumée s'enroule vers le haut ». Évitez les instructions qui contredisent la scène — faire marcher un sujet assis, ou exiger un panoramique rapide sur un plan produit fixe, provoque généralement des artefacts.

Rester bref et précis

Deux ou trois phrases concrètes et physiques valent mieux qu'un paragraphe entier d'adjectifs. Indiquez d'abord le mouvement principal, puis la caméra, puis les détails secondaires comme les changements de lumière.

Soumettre une tâche et interroger le résultat

La génération vidéo prend du temps : l'API est donc asynchrone. Le cycle de vie se déroule en trois étapes :

1. Créer la tâche

Envoyez en POST l'URL de l'image, le prompt et les paramètres à l'endpoint. Une réponse réussie renvoie un identifiant de tâche et un état initial, généralement du type queued ou processing. La vidéo n'est pas encore présente dans cette réponse.

2. Interroger la tâche

Envoyez périodiquement des requêtes GET pour cet identifiant de tâche. Chaque réponse indique l'état et, une fois terminée, contient aussi la charge utile du résultat. Interrogez à un intervalle raisonnable — généralement de quelques secondes — plutôt que dans une boucle serrée, et limitez le nombre de tentatives pour qu'une tâche bloquée ne suspende pas indéfiniment votre processus.

3. Récupérer la vidéo

Lorsque l'état signale un succès, la réponse contient l'emplacement de la vidéo (généralement une URL), souvent avec des métadonnées comme la durée. Téléchargez-la ou stockez-la selon vos propres règles de conservation.

Points de conception pour la production

  • Persistez l'ID de tâche. Si votre worker plante en cours de polling, vous voulez pouvoir reprendre plutôt que de resoumettre et payer pour une tâche en double.
  • Gérez les échecs terminaux. Une tâche peut échouer ; traitez l'échec comme une branche distincte, et non comme « continuer à interroger ».
  • Découplez la soumission et le polling. Dans un backend web, soumettez depuis le gestionnaire de requête et interrogez depuis un worker en arrière-plan, afin qu'un timeout HTTP ne tue jamais une génération en cours.

Exemple curl exécutable

L'exemple suivant soumet une tâche. Remplacez l'URL d'image et le prompt par les vôtres ; la clé provient de la variable d'environnement définie plus haut.

curl -sS -X POST \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "prompt": "Le sujet se tourne légèrement vers la caméra et sourit ; la caméra avance lentement, une lumière douce glisse sur le visage."
  }'

La réponse contient un identifiant de tâche. Interrogez-le avec une requête GET :

curl -sS \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Répétez jusqu'à un état de succès terminal, puis lisez l'URL de la vidéo dans la charge utile. Le chemin d'endpoint et les noms de champs exacts montrés ici servent uniquement à illustrer le schéma — vérifiez-les dans la documentation de référence de l'API la plus récente avant de coller quoi que ce soit dans du code de production, car les interfaces des modèles changent bel et bien.

Exemple Python exécutable

Ce script soumet une tâche, puis interroge jusqu'à l'achèvement, avec timeout et gestion d'erreur basique.

import os
import time

import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def create_task(image_url: str, prompt: str) -> str:
    resp = requests.post(
        BASE,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image_url": image_url, "prompt": prompt},
        timeout=60,
    )
    resp.raise_for_status()
    data = resp.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"No task id in response: {data}")
    return task_id


def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = str(data.get("status", "")).lower()
        if status in {"succeeded", "success", "completed"}:
            return data
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task = create_task(
        image_url="https://your-cdn.example.com/first-frame.jpg",
        prompt="De la vapeur s'élève de la tasse ; la caméra dérive lentement vers la droite.",
    )
    result = poll_task(task)
    print(result)

Comme les chaînes d'état peuvent varier selon les versions de l'API, le code vérifie un petit ensemble de valeurs courantes de succès et d'échec plutôt qu'un seul littéral — vérifiez le vocabulaire exact dans la documentation de référence de l'API et ajustez l'ensemble en conséquence. Si vous construisez plusieurs pipelines média, isoler cette fonction utilitaire facilite sa réutilisation.

Modes d'échec courants et méthodes de débogage

La plupart des problèmes sur cet endpoint se rangent dans les catégories suivantes.

Image rejetée ou inaccessible

Le service doit pouvoir télécharger votre image. En cas d'erreur de récupération ou de validation, vérifiez que l'URL est bien en HTTPS public, qu'elle n'a pas expiré (les URL signées expirent) et que le format et la taille respectent les limites de la documentation. Un test rapide consiste à ouvrir l'URL dans une fenêtre de navigation privée — si elle demande une connexion, le serveur ne pourra pas la lire non plus.

Paramètres invalides

Une durée, une résolution ou un champ inconnu rejeté renvoie généralement une erreur de validation qui désigne le champ concerné. Comparez votre charge utile à la documentation de référence de l'API la plus récente, pas à un tutoriel, et journalisez le corps d'erreur complet — le message est plus précis que le simple code de statut HTTP.

Erreurs d'authentification

Un 401 ou 403 signifie presque toujours une clé absente, mal formée ou sans droits d'accès. Vérifiez que l'en-tête Authorization est présent, et que la variable d'environnement est bien exportée dans le shell ou le processus qui exécute la requête.

Timeout de polling

Si une tâche est encore processing après votre timeout, vérifiez d'abord que vous interrogez le bon ID de tâche, puis allongez le timeout. En production, distinguez « toujours en cours » de « bloquée » : persistez l'état et laissez un worker reprendre le polling, plutôt que de resoumettre, car resoumettre gaspille des tâches.

Tâche échouée après soumission

Une tâche échouée pointe généralement vers la combinaison prompt/image — instructions de mouvement contradictoires, ou première image en conflit avec le mouvement demandé. Simplifiez le prompt, essayez une première image plus propre, puis relancez.

Rendu qui semble incorrect

Si le mouvement est faible ou bizarre, la correction tient presque toujours au prompt : précisez le mouvement principal, séparez le comportement de la caméra de celui du sujet, et gardez un mouvement physiquement plausible. Journalisez l'ID de requête et l'ID de tâche pour pouvoir associer un clip médiocre aux entrées exactes qui l'ont produit. Avant de publier, vérifiez les noms de paramètres et les tarifs actuels dans la documentation de référence de l'API et le panneau tarifaire.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API