Blog

Tutoriel

Appeler veo-3.1/image-to-video via l'API HiAPI : tutoriel curl et Python

Nov 12, 2026
Image de couverture : des feuilles de papier blanc cassé empilées en couches décalées, une feuille intercalaire rouge rouille au milieu, une ombre portée rectiligne.
Sur cette page

Ce qu'attend le point de terminaison veo-3.1 image-vers-vidéo

Avant d'écrire la première ligne de code, il est utile de bien comprendre de quel type d'appel il s'agit. veo-3.1/image-to-video ne renvoie pas la vidéo directement dans la réponse HTTP où vous envoyez votre prompt. C'est un point de terminaison de tâche asynchrone : vous décrivez la vidéo souhaitée, la plateforme accepte la tâche, puis vous revenez consulter le résultat.

Conceptuellement, une requête comporte deux parties bien distinctes :

  • L'image de première frame. C'est l'image fixe de départ à partir de laquelle la vidéo est générée. Elle ancre la composition, le sujet et le rendu du moment d'ouverture. Tout ce qui suit est généré par le modèle à partir de ce point de départ.
  • Les options de génération. Ce sont les paramètres qui contrôlent la façon dont la vidéo est générée — par exemple s'il faut générer l'audio, la résolution de sortie et la durée du clip.

Cette séparation est importante pour deux raisons. D'abord, elle rend le diagnostic des pannes plus simple : un problème d'image ne ressemble pas à un problème de paramètre, et vous voulez pouvoir distinguer les deux. Ensuite, cela signifie que votre code doit être organisé de la même manière — une partie de la logique prépare l'image, une autre construit l'ensemble d'options.

L'appelant doit au minimum fournir : une image de première frame valide, ainsi que les décisions concernant l'audio, la résolution et la durée. Tout le reste — soumettre la tâche, suivre l'état, récupérer la vidéo finale — est pris en charge par le cycle de vie des tâches de la plateforme. Votre intégration n'a que trois choses à faire : envoyer une requête correctement formée, mémoriser l'identifiant de tâche renvoyé, et interroger jusqu'à ce que la tâche atteigne un état terminal.

Un conseil pratique avant de continuer : comme l'appel est asynchrone, votre code ne peut pas supposer que la vidéo est disponible immédiatement après la soumission. Concevez votre flux autour de ce point dès le début, et la suite du tutoriel paraîtra naturelle.

Le modèle mental en deux parties

Gardez ce cadre en tête lors de la lecture des sections suivantes :

  1. Entrée → image de première frame préparée et validée.
  2. Options → audio, résolution, durée.
  3. Tâche → soumission, obtention de l'identifiant, interrogation, récupération.

Chaque section ci-dessous correspond à l'une de ces cases.

Préparer l'image de première frame

L'image de première frame est l'entrée unique la plus importante d'un appel image-vers-vidéo, alors donnez-lui une étape dédiée dans votre pipeline plutôt que de l'enfouir dans le constructeur de requête. L'appel API doit pouvoir référencer cette image, ce qui signifie qu'elle doit être dans une forme acceptable et lisible par la plateforme.

Ce qu'il faut vérifier avant l'envoi

  • L'image s'ouvre réellement. Un téléchargement tronqué ou un fichier corrompu est la cause la plus fréquente d'échecs déroutants en aval. Avant d'envoyer quoi que ce soit, vérifiez qu'elle se décode correctement.
  • Le format est accepté par la plateforme. Si votre source est une capture d'écran, une photo de téléphone ou un export d'outil de design, normalisez-la vers un format largement pris en charge avant l'envoi. Une conversion anticipée est plus simple qu'un débogage ultérieur.
  • Les dimensions sont raisonnables. Une image minuscule ou extrêmement étirée fournit peu de matière au modèle. Si la source est trop petite, envisagez un agrandissement ou choisissez une meilleure frame.
  • La composition est un bon point de départ. Comme c'est la première frame, le mouvement généré en découle. Choisissez une frame où le sujet est clairement visible et dont vous êtes content de voir la composition au début du clip.

La garder séparée des options

Organisez le code de sorte que la préparation de l'image renvoie une référence à transmettre au constructeur de requête, plutôt que de mélanger le traitement de l'image avec l'assemblage des paramètres. Concrètement :

# Structure en pseudo-code, pas un client complet
def prepare_first_frame(path):
    image = load_and_validate(path)   # décoder, vérifier le format, vérifier les dimensions
    ref = upload_or_encode(image)     # produire un contenu référençable par l'appel API
    return ref

def build_request(first_frame_ref, options):
    return {
        "first_frame": first_frame_ref,
        # audio / résolution / durée ici
    }

Cette séparation est payante au débogage. Si une tâche échoue, vous pouvez relancer prepare_first_frame séparément pour confirmer que le côté image est sain avant de toucher aux paramètres de génération.

Valider tôt, échouer bruyamment

Effectuez la validation de votre côté et levez des erreurs claires en cas d'échec. Une image mal formée ou illisible ne doit jamais atteindre le réseau — la détecter localement transforme un échec de tâche asynchrone vague en une exception précise et immédiate que vous avez écrite vous-même.

Définir les options de génération : audio, résolution et durée

Une fois l'image traitée, les décisions restantes portent sur les options de génération. Elles modifient la nature de la sortie, il faut donc les traiter comme des paramètres nommés explicites, et non comme des valeurs magiques enfouies dans le corps de la requête.

Audio

L'option audio contrôle si la vidéo générée contient une piste sonore. C'est à la fois une décision technique et une décision produit :

  • Si la vidéo est intégrée en silence — boucle d'arrière-plan, visuel principal en lecture automatique — l'audio n'est généralement pas nécessaire, et l'omettre simplifie le traitement en aval.
  • Si le clip doit être présenté avec du son de manière autonome — contenu social court, démonstration — activez l'audio, pour qu'un seul appel produise l'élément complet.

Décidez-en consciemment selon le cas d'usage, plutôt que d'adopter aveuglément la valeur par défaut ; cela influence à la fois la sortie et la façon dont votre pipeline en aval traitera le fichier.

Résolution

La résolution détermine les dimensions en pixels de la vidéo finale. Choisissez-la selon l'endroit où la vidéo sera affichée et le niveau de détail nécessaire au contenu, plutôt que de simplement prendre « la valeur maximale disponible ». Un clip destiné à un petit lecteur intégré ne gagne rien à être généré dans une taille bien supérieure aux capacités de l'écran. Si la plateforme publie un ensemble de valeurs prises en charge, choisissez-en une explicitement et validez-la côté client, pour que les valeurs non prises en charge échouent rapidement.

Durée

La durée fixe la longueur du clip généré. Elle interagit avec votre planification de contenu : un plan qui doit d'abord établir la scène puis montrer le mouvement demande plus de temps qu'un simple geste. Notez qu'il s'agit probablement de l'un des paramètres les plus susceptibles d'être mesurés — la facturation de la plateforme est décrite en fonction de la sortie générée, alors surveillez la longueur des clips lors de requêtes en lot.

Assembler les options en un objet

Placez les trois dans une même structure d'options, pour n'avoir qu'un seul endroit à consulter et un seul à modifier :

options = {
    "audio": True,          # générer la piste audio
    "resolution": "...",    # l'une des valeurs prises en charge
    "duration": 8,          # durée de la vidéo générée en secondes
}

Utilisez les valeurs indiquées comme prises en charge par votre compte et la documentation actuelle du point de terminaison — lisez-les dans la documentation plutôt que de les coder en dur au hasard, et validez-les lors de la construction de la requête, pour qu'une valeur erronée ne devienne jamais une tâche en échec.

Soumettre la tâche avec curl

Assemblez maintenant les deux parties et soumettez. Commencez par la ligne de commande, car curl rend la forme de la requête visible et vous donne un moyen de tester rapidement les modifications avant d'écrire du code.

La requête

La requête de soumission ressemble structurellement à ceci — remplacez les valeurs de substitution par vos propres identifiants, référence d'image et valeurs d'options :

curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_frame": "<référence d'image issue de l'étape d'envoi>",
    "audio": true,
    "resolution": "<valeur prise en charge>",
    "duration": 8
  }'

Quelques conventions à adopter :

  • Placez la clé dans une variable d'environnement ($HIAPI_API_KEY) plutôt que de la coller dans la commande. Cette habitude se prolonge directement dans votre code Python et garde la clé hors de l'historique du shell.
  • Envoyez le JSON avec un en-tête Content-Type explicite.
  • Séparez la référence d'image des options numériques et booléennes dans le corps de la requête, en écho au modèle en deux parties de la première section.

Lire la réponse

Comme il s'agit d'un point de terminaison asynchrone, une réponse réussie n'est pas la vidéo. C'est seulement la confirmation que la tâche a été acceptée, avec les informations nécessaires pour la suivre — surtout l'identifiant de tâche, et généralement un champ d'état indiquant qu'elle est en file ou en cours d'exécution.

Lisez en deux étapes. D'abord, confirmez que le statut HTTP indique une acceptation et non une erreur client. Ensuite, analysez le corps de la réponse et extrayez l'identifiant de tâche :

curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | tee submit.json

En écrivant la réponse dans submit.json, vous avez de quoi l'inspecter et l'utiliser dans l'étape d'interrogation. Si la soumission échoue, le corps de la réponse d'erreur est votre première et meilleure piste — vérifiez s'il pointe vers la référence d'image ou vers une option, puis corrigez uniquement cette moitié et soumettez à nouveau.

Interroger la tâche asynchrone jusqu'à ce que la vidéo soit prête

Une fois l'identifiant de tâche en main, le flux de travail devient une boucle : demander l'état de la tâche à la plateforme, et s'arrêter lorsque la tâche atteint un état terminal.

Le cycle de vie

Une tâche image-vers-vidéo passe par un petit nombre d'états. Elle est acceptée et mise en file, puis traitée, et finalement soit réussit en produisant une vidéo, soit échoue avec une erreur. Votre code d'interrogation n'a besoin de distinguer que trois choses :

  • Toujours en traitement — continuer à attendre.
  • Succès — lire l'emplacement de sortie et télécharger ou stocker la vidéo.
  • Échec — arrêter et lever une erreur.

Interroger de manière responsable

Deux habitudes rendent l'interrogation plus robuste :

  1. Attendre entre les vérifications. Une boucle serrée qui martèle le point de terminaison d'état gaspille des requêtes sans rien apporter ; la génération prend un temps réel. Utilisez un intervalle fixe ou un backoff modéré.
  2. Définir une échéance. N'interrogez jamais indéfiniment. Choisissez un nombre maximal de tentatives ou une durée maximale, et traitez son dépassement comme un échec clairement rapportable.
# Ébauche de boucle d'interrogation
for i in $(seq 1 60); do
  status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$status"
  # sortir lorsque le champ d'état indique un succès ou un échec
  sleep 5
done

Traitez les chaînes d'état exactes et les chemins de point de terminaison comme des éléments à vérifier par rapport à la documentation API actuelle, plutôt que comme des hypothèses figées dans le script.

En cas de succès

Lorsque la tâche signale un succès, la réponse contient l'emplacement de la vidéo finale. Téléchargez-la rapidement et stockez-la dans un emplacement persistant — le résultat d'une tâche sur n'importe quelle plateforme asynchrone doit être considéré comme quelque chose à récupérer maintenant, et non à charger paresseusement bien plus tard. Consignez l'identifiant de tâche avec le fichier stocké, pour que toute sortie puisse être retracée jusqu'à la requête qui l'a produite.

La même requête en Python

La version Python ne doit pas être une seconde implémentation — mais la même requête, exprimée une fois et réutilisée. L'objectif est une seule fonction qui soumet et interroge, construite à partir de la même référence d'image et du même objet d'options que vous avez validés précédemment.

Un corps de requête, un client

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
})

def build_body(first_frame_ref, options):
    return {"first_frame": first_frame_ref, **options}

def submit(body):
    r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
    r.raise_for_status()
    data = r.json()
    return data["job_id"]

def poll(job_id, interval=5, max_attempts=60):
    for _ in range(max_attempts):
        r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        state = data.get("status")
        if state in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"La tâche {job_id} n'a pas pu se terminer à temps")

def image_to_video(first_frame_ref, options):
    job_id = submit(build_body(first_frame_ref, options))
    result = poll(job_id)
    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "Échec de la tâche"))
    return result  # contient l'emplacement de la vidéo finale

Pourquoi cette forme

  • Une seule Session. Réutiliser la session place l'en-tête d'authentification au même endroit et réutilise la connexion entre la soumission et chaque interrogation.
  • Un seul build_body. La requête curl et la requête Python sont le même corps — mêmes clés, mêmes valeurs. Quand vous modifiez une option, vous la modifiez à un seul endroit.
  • Délais d'attente et échéances explicites. Les deux appels définissent un timeout, et poll a une limite de tentatives, pour qu'une tâche bloquée ne suspende jamais votre processus.
  • Les échecs sont exposés bruyamment. Le raise_for_status lors de la soumission capture immédiatement les erreurs au niveau de la requête ; la branche d'échec explicite dans image_to_video capture les échecs au niveau de la tâche.

Si vous devez plus tard appeler d'autres modèles via la même plateforme, cette structure se généralise : la session, la fonction auxiliaire de soumission et la fonction auxiliaire d'interrogation restent identiques, seuls le point de terminaison et le constructeur de corps changent.

Diagnostiquer les appels image-vers-vidéo en échec

Lorsqu'un appel ne produit pas de vidéo, réduisez le champ en demandant quelle étape a échoué. Le modèle de requête en deux parties vous donne une liste de vérification claire.

Étape 1 : la soumission est refusée

Si l'appel de soumission lui-même renvoie une erreur, rien n'a été généré — c'est une bonne nouvelle, car le problème se trouve dans la requête.

  • Problème de référence d'image. La cause unique la plus fréquente. Relancez l'étape de préparation de l'image séparément et confirmez qu'elle produit une image valide, lisible, au bon format, et une référence acceptée par l'API. Vérifiez d'abord les téléchargements tronqués et les formats non pris en charge.
  • Valeurs d'option invalides. Une résolution non prise en charge ou une durée hors limites sera rejetée lors de la soumission. Validez les options par rapport aux valeurs prises en charge de la documentation avant l'envoi.
  • Authentification et en-têtes. Confirmez que la clé est bien envoyée (Authorization: Bearer ...) et que le corps est envoyé en JSON. Lors d'une construction manuelle de la requête en curl, un corps vide ou malformé est facile à négliger.

Étape 2 : la tâche est soumise mais échoue

Si la soumission est acceptée mais que l'interrogation se termine en échec, cela signifie que la requête est bien formée, et que le problème vient du contenu ou de la tâche elle-même.

  • Lisez l'erreur de la tâche. La réponse d'échec explique mieux ce qui a mal tourné que toute supposition. Consignez-la telle quelle.
  • Examinez la première frame. Une image source sans sujet clair, avec un cadrage extrême ou fortement déformée fournit peu de matière au modèle. Remplacez-la par une frame plus propre et réessayez.
  • Remettez les options en question. Une durée très longue ou une combinaison de paramètres inhabituelle mérite d'être retestée avec une configuration plus simple, pour isoler le paramètre problématique.

Étape 3 : l'interrogation ne se termine jamais

Si votre boucle expire au lieu d'échouer, traitez cela comme un problème d'infrastructure, et non de contenu. Confirmez que vous interrogez le bon identifiant de tâche, que l'intervalle n'est pas trop agressif, et que l'échéance est suffisamment longue pour la durée demandée. Consignez l'identifiant de tâche dès la soumission — sans lui, vous ne pouvez tout simplement pas enquêter sur une tâche bloquée.

Un flux de débogage efficace

En cas de problème, procédez dans cet ordre : validez l'image localement, soumettez à nouveau et capturez la réponse brute, examinez l'erreur de tâche si elle existe, puis simplifiez les options et réessayez. Chaque étape teste exactement une moitié de la requête, et c'est pourquoi séparer l'image et les paramètres de génération dans le code est payant précisément en cas d'erreur.

Vous disposez maintenant de la boucle complète : préparer la première frame, définir l'audio, la résolution et la durée, soumettre de manière asynchrone, et interroger jusqu'à l'achèvement — le tout avec la même requête, qu'elle soit exécutée en curl ou en Python.

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