Blog

Tutoriel

Comment appeler kling-4.0-flash Reference-to-Video via l'API HiAPI : pratique avec curl et Python

Pratique d'appel exécutable pour la génération vidéo à partir de plusieurs images de référence, polling asynchrone et guide de dépannage

Nov 12, 2026
Image de couverture : deux grands aplats de couleur, l'un lilas pâle et l'autre noir d'encre, se rejoignent le long d'une arête droite et nette, bordée d'une fine couture violette ; la composition est sobre et apaisée.
Modèle
kling-4.0-flash
Sur cette page

Quand utiliser la génération vidéo à partir d'images de référence plutôt que la génération texte-vers-vidéo

La génération texte-vers-vidéo est l'outil du scénariste : vous décrivez une scène et le modèle crée tout de zéro. La génération à partir d'images de référence est l'outil du réalisateur : vous fournissez une ou plusieurs images au modèle et lui demandez de produire une séquence animée dans laquelle ces sujets, ce style ou cette composition restent reconnaissables. Sur HiAPI, cette distinction se situe au niveau du point de terminaison — kling-4.0-flash/reference-to-video est une route distincte des appels texte-vers-vidéo classiques ; choisir le bon point de terminaison en amont évite de s'enfermer dans un travail d'ingénierie de prompts qui ne restituera jamais tout à fait une apparence spécifique.

Choisissez la génération à partir d'images de référence lorsque l'une des situations suivantes se présente :

  • La cohérence d'identité ou de produit est essentielle. Vous disposez d'une fiche de personnage, d'une photo de produit ou d'une mascotte, et la sortie ne doit pas dériver vers une figure générique ressemblante.
  • Vous devez combiner plusieurs sources. Une scène peut nécessiter une image pour définir le personnage et une autre pour définir l'environnement ou le vêtement. Plusieurs images de référence vous permettent d'exprimer explicitement cette composition plutôt que de la décrire en prose.
  • Le transfert de style est l'objectif même. Vous souhaitez transposer la palette, l'éclairage ou le style de rendu de l'image fournie dans une séquence animée.
  • Vous itérez sur un plan. Les images de référence rendent plusieurs exécutions comparables, car l'ancrage visuel reste fixe et vous n'ajustez que les paramètres liés au mouvement.

Continuez à utiliser la génération texte-vers-vidéo lorsque vous explorez des concepts, que vous ne disposez pas d'images aux droits clairs pour servir d'ancrage, ou que le besoin lui-même est abstrait (« un lent survol aérien à travers la brume à l'aube ») et que toute interprétation raisonnable convient. Les images de référence contraignent le modèle, et une contrainte n'est bénéfique que lorsque vous en avez réellement besoin.

Règle pratique : si vous vous surprenez à écrire un paragraphe entier pour décrire l'apparence exacte d'un objet précis, c'est le signal de basculer vers ce point de terminaison et de fournir directement l'image. La description coûte des tokens et dérive encore ; l'image de référence ancre.

Structure de la requête : images de référence et paramètres essentiels

Le point de terminaison accepte un corps de requête JSON. Les éléments que vous manipulerez réellement se répartissent en trois catégories : les images de référence, le prompt et les paramètres qui façonnent la sortie.

Images de référence

Les images de référence sont transmises sous forme de tableau, ce qui permet naturellement de passer d'une image à plusieurs dans le même champ. Chaque entrée est une URL que le service doit pouvoir récupérer. Contraintes pratiques à prendre en compte lors de la conception :

  • Utilisez des URL HTTPS accessibles publiquement, ou des URL auxquelles votre compte a accès. Les chemins de fichiers locaux et les URI file:// ne peuvent pas être récupérés par un service distant.
  • Privilégiez un hébergement stable plutôt qu'un lien signé qui expire au bout de quelques minutes — une tâche de longue durée peut récupérer l'image à un moment que vous n'avez pas anticipé.
  • Gardez chaque image ciblée. Une image propre du sujet aide davantage qu'un collage encombré, car le modèle doit discerner ce qu'il voit.
  • L'ordre peut influencer la manière dont les images de référence sont interprétées ; dans le code, rendez donc l'ordre du tableau déterministe plutôt que de dépendre de l'ordre d'itération d'un dictionnaire.

Prompt

Une fois les images de référence fournies, le prompt doit décrire le mouvement, la caméra et l'ambiance, et non l'apparence. Indiquez comment le sujet se déplace, comment la caméra bouge, quel est le rythme ressenti. Redécrire les images de référence gaspille le budget du prompt et peut entrer en conflit avec l'ancrage que vous venez de fournir.

Paramètres qui façonnent la sortie

Outre prompt et le tableau d'images de référence, le corps de la requête comporte généralement des champs contrôlant le format de sortie et le comportement de génération. Considérez-les comme les derniers boutons à ajuster : commencez par réussir l'appel avec les valeurs par défaut, vérifiez que les images de référence sont bien respectées, puis ajustez les paramètres de sortie. Les noms de champs et les valeurs autorisées sont définis dans la documentation de référence du point de terminaison ; envoyer un champ non reconnu est une cause fréquente de rejet du corps de requête, validez donc selon le schéma documenté plutôt que par supposition.

Le modèle mental est simple : les images de référence indiquent quoi, le prompt indique comment cela se meut, les paramètres indiquent ce que vous récupérez.

Requête curl prête à l'emploi

Avant d'écrire du code client, le moyen le plus fiable de vérifier le corps de requête est un appel curl. Placez les identifiants et les entrées dans des variables shell, gardez le JSON lisible, puis envoyez la requête.

API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai"   # utilisez l'URL de base affichée dans votre console

curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Le personnage se tourne vers la fenêtre, la caméra avance lentement ; lumière douce du matin, rythme calme.",
    "reference_images": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/location-window.jpg"
    ]
  }'

Vérifiez trois choses avant d'exécuter :

  1. Le chemin et le préfixe de version. Confirmez la route exacte avec la documentation du point de terminaison de votre compte ; le chemin comporte un numéro de version, et un préfixe obsolète renvoie « introuvable » plutôt qu'une erreur de validation.
  2. L'en-tête d'authentification. La clé se place sous forme de bearer token dans l'en-tête Authorization. Ne la mettez jamais dans le corps de la requête ni dans la chaîne de requête, sinon elle fuitera dans les journaux.
  3. Les espaces réservés. Chaque valeur à remplacer est manifestement un espace réservé — le commentaire de l'URL de base, les deux URL CDN, le prompt. Avant de déclarer le code prêt pour la production, recherchez example.com dans la requête.

Une soumission réussie renvoie un identifiant de tâche, et non la vidéo terminée. Récupérez cet identifiant dans le corps de la réponse ; il sera nécessaire pour le polling à l'étape suivante. Faire passer la réponse par un formateur JSON (| jq .) met l'ID de tâche en évidence, et cela vaut la peine d'en faire une habitude.

La même requête en Python

La différence principale de la version Python réside dans la construction du corps de requête : construisez un dict, sérialisez-le une fois, et séparez la fonction d'envoi de la logique de polling afin de pouvoir les tester indépendamment.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]

REFERENCE_IMAGES = [
    "https://your-cdn.example.com/refs/character-front.png",
    "https://your-cdn.example.com/refs/location-window.jpg",
]

def submit_reference_video(prompt: str) -> str:
    payload = {
        "prompt": prompt,
        "reference_images": REFERENCE_IMAGES,
    }
    response = requests.post(
        f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

if __name__ == "__main__":
    task_id = submit_reference_video(
        "Le personnage se tourne vers la fenêtre, la caméra avance lentement."
    )
    print("submitted:", task_id)

Les précautions suivantes évitent bien des tracas :

  • Lisez la clé depuis une variable d'environnement. Une clé codée en dur finit tôt ou tard dans l'historique git et les captures d'écran.
  • Utilisez json= plutôt que data=, afin que le client définisse correctement le type de contenu et échappe le corps de la requête.
  • Définissez un timeout explicite. L'attente infinie par défaut transforme une connexion bloquée en processus de travail suspendu.
  • Appelez raise_for_status() avant l'analyse, afin qu'une réponse 4xx soit signalée comme erreur HTTP plutôt que de provoquer un KeyError déroutant sur le JSON de réponse.
  • Confirmez dans la documentation le nom du champ de réponse contenant l'identifiant de tâche au lieu de supposer qu'il s'agit de task_id ; ajustez la ligne d'extraction en conséquence.

Faites en sorte que submit_reference_video ne renvoie que l'ID. Le polling est une préoccupation distincte, à placer dans sa propre fonction.

Gérer le cycle de vie des tâches asynchrones

La génération vidéo prend du temps, c'est pourquoi ce point de terminaison est asynchrone par conception. L'appel de soumission renvoie rapidement un identifiant de tâche ; le travail réel a lieu ensuite. Votre intégration doit modéliser cela, et le modèle correct le plus simple comporte trois états : pending ou processing (continuer d'attendre), succeeded (récupérer la sortie), failed (lire l'erreur et s'arrêter).

Interrogez le point de terminaison de la tâche à intervalles réguliers, avec une durée d'attente totale plafonnée :

import time

def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    url = f"{BASE_URL}/v1/tasks/{task_id}"
    while time.monotonic() < deadline:
        r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")

Adaptez les chaînes d'état et le chemin de la tâche à ce que prescrit la documentation — la structure ci-dessus n'est qu'un modèle, et la plupart des échecs dans ce domaine proviennent d'une étiquette d'état supposée qui n'existe pas.

Bonnes pratiques de polling à adopter tôt :

  • Retrait progressif. Un intervalle court fixe martèle l'API sans bénéfice. Commencez par une valeur modérée et augmentez le temps de sommeil entre les tentatives.
  • Toujours borner la boucle. Un while True autour d'une tâche distante, c'est attendre qu'une panne survienne. La date limite ci-dessus lève une exception au lieu de suspendre.
  • Persistez l'ID de tâche. Si votre processus plante après la soumission, cet ID est le seul moyen de récupérer le résultat sans payer une seconde génération.
  • Traitez failed comme un état terminal. Ne réessayez pas une tâche échouée en la réinterrogeant ; lisez l'erreur et, le cas échéant, resoumettez une requête corrigée.
  • Gérez l'expiration explicitement. Les résultats de tâche peuvent ne pas être disponibles indéfiniment ; téléchargez et stockez donc la sortie dès qu'une tâche réussit.

Erreurs courantes et comment les corriger

La plupart des échecs d'intégration initiaux relèvent de quelques catégories. Avant de modifier le code, associez le symptôme à la cause.

Échecs d'authentification et d'autorisation

Un 401 ou 403 signifie presque toujours des identifiants erronés, manquants ou de portée incorrecte. Vérifiez que l'en-tête est exactement Authorization: Bearer <key>, que la variable d'environnement est bien renseignée dans le processus qui effectue l'appel (un export shell ne se propage pas à une unité systemd), et que la clé n'a pas été renouvelée ou révoquée.

Problèmes d'images de référence

Si la requête est rejetée à cause d'une image, ou que la génération ignore une image de référence, le suspect est l'URL. Vérifiez que le lien se résout depuis l'extérieur de votre machine — un nom d'hôte interne ou une adresse localhost est inaccessible pour le service. Vérifiez la date d'expiration des URL signées, vérifiez que le fichier est bien une image et non une page d'erreur HTML renvoyée avec un statut 200, et vérifiez les limites de taille et de format. Une seule mauvaise entrée dans un tableau de plusieurs images peut faire échouer toute la requête ; testez donc les images de référence une par une lors du débogage.

Corps de requête invalide

Un 400 accompagné d'un message de validation signifie généralement un corps de requête mal formé : un tableau au niveau supérieur au lieu d'un objet, un champ obligatoire manquant, reference_images envoyé comme chaîne entre guillemets au lieu d'un tableau, ou un nom de paramètre non reconnu. Comparez votre corps de requête champ par champ avec le schéma documenté, et journalisez le corps exact que vous envoyez — le défaut est souvent une différence de sérialisation entre le chemin de test et le chemin de production.

Erreurs de route ou de méthode

Un 404 signifie généralement un chemin erroné, et non un modèle indisponible. Revérifiez le préfixe de version et le nom du point de terminaison dans la documentation, et confirmez que la soumission utilise POST et la consultation du statut GET.

Erreurs de délai d'attente et de polling

Si la soumission elle-même expire, augmentez modérément le timeout client et réessayez — mais si la tâche a déjà été acceptée, ne resoumettez pas à l'aveugle, sinon vous paierez une génération en double. Si le polling ne se termine jamais, votre vérification d'état compare probablement la mauvaise chaîne ; journalisez la valeur d'état brute lors des premières itérations pour voir ce qui est réellement renvoyé.

Limitation de débit

Un 429 signifie qu'il faut ralentir. Respectez l'intervalle indiqué au lieu de réessayer immédiatement, et appliquez un retrait exponentiel avec jitter pour éviter que des processus parallèles ne réessaient en cadence.

Liste de contrôle avant mise en production

Un code qui fonctionne dans un notebook n'est pas une intégration fiable. Avant d'exposer ce point de terminaison à vos utilisateurs, resserrez les limites opérationnelles.

  • Configuration. Conservez l'URL de base et la clé API dans des variables d'environnement ou un gestionnaire de secrets, jamais dans le code source. Faites du chemin du point de terminaison une constante, afin qu'une montée de version ne tienne qu'en une ligne.
  • Nouvelle tentative avec retrait. Pour les défaillances transitoires — réinitialisations de connexion, 429, 5xx — réessayez avec un retrait exponentiel et du jitter. Ne réessayez pas les erreurs de validation 4xx ; elles échoueront de la même façon.
  • Discipline d'idempotence. Enregistrez chaque ID de tâche soumis ainsi que ses entrées. Au redémarrage, reprenez le polling des tâches existantes plutôt que d'en soumettre de nouvelles.
  • Attente bornée. Définissez des délais explicites à la fois pour le client HTTP et pour la boucle de polling, et acheminez les délais vers un chemin de messages morts vérifiable par un humain plutôt que de les abandonner silencieusement.
  • Journalisation structurée. Journalisez les ID de tâche, les transitions d'état horodatées, les temps de soumission et de fin, ainsi que le corps d'erreur en cas d'échec. Masquez les clés et tronquez les prompts lorsqu'ils contiennent des données utilisateur.
  • Traitement des sorties. Dès qu'une tâche réussit, téléchargez le média généré vers votre propre stockage et validez le résultat avant de le présenter à l'utilisateur.
  • Visibilité des coûts. La facturation varie selon l'usage ; suivez donc le nombre de tâches soumises par fonctionnalité et par utilisateur. Les boucles de nouvelle tentative qui resoumettent en situation d'incertitude sont la cause la plus fréquente de dépenses imprévues.
  • Hygiène des entrées. Validez d'abord de votre côté les URL de référence et la longueur du prompt. Détecter une mauvaise URL localement est plus rapide et moins coûteux qu'un aller-retour réseau.

Une fois cela fait, l'intégration est une couche légère et prévisible : construire le corps de requête, soumettre, interroger, stocker. Commencez par la documentation de référence du point de terminaison, exécutez l'exemple curl, puis transposez le même corps de requête en Python — une requête qui fonctionne dans le shell fonctionnera aussi dans votre service.

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