Blog

Tutoriel

Comment utiliser kling-4.0-flash image-to-video via l'API HiAPI : curl et Python

Exercice pratique de requête : entrée d'image de première frame, interrogation asynchrone des tâches, audio synchrone et dépannage des erreurs

Nov 12, 2026
Image de couverture : une pile de feuilles blanc cassé disposées en décalage, aux bords soulignés de noir de charbon, entre lesquelles s'intercale une page de garde rouge rouille, projetant en dessous une ombre nette.
Modèle
kling-4.0-flash
Sur cette page

Rôle du point de terminaison kling-4.0-flash image-to-video

kling-4.0-flash/image-to-video est un modèle de génération vidéo conditionné par une image. Vous lui fournissez une image — la première frame — accompagnée d'un prompt texte, et il renvoie une vidéo générée qui commence à partir de cette frame et évolue selon votre description.

Le point le plus important à intégrer avant d'écrire du code : il ne s'agit pas d'un appel requête/réponse qui renvoie les octets de la vidéo dans le même échange HTTP. La génération prend du temps, donc ce point de terminaison suit un modèle de tâche asynchrone. Votre première requête soumet une tâche ; vous récupérez ensuite le résultat en interrogeant l'état de la tâche jusqu'à ce qu'elle atteigne un état terminal.

Gardez ces trois concepts distincts en tête, car ils correspondent à trois parties différentes du client :

  • Soumission — la charge utile que vous envoyez : l'image de première frame, le prompt et les options de génération.
  • Référence de tâche — l'identifiant renvoyé lors de la soumission, utilisé pour interroger la tâche plus tard.
  • Récupération du résultat — la vérification répétée de l'état, qui renvoie finalement la vidéo terminée (ou une erreur).

Une fois que vous traitez le point de terminaison comme une file de tâches plutôt que comme un RPC, le reste de l'intégration — intervalle d'interrogation, délais d'attente, nouvelles tentatives — devient un simple pipeline asynchrone au lieu d'un cas particulier. Si vous souhaitez consulter en parallèle une documentation plus complète des points de terminaison en plus de cet exercice, ouvrez-la dans un autre onglet et suivez-la en même temps.

Avant d'envoyer la requête

Trois éléments doivent être prêts avant le premier appel.

1. Identifiants d'API

Vous avez besoin d'une clé d'API HiAPI. Chaque requête doit l'envoyer sous forme de jeton bearer dans l'en-tête Authorization. Ne la placez pas dans le contrôle de version — lisez-la depuis une variable d'environnement plutôt que de la coller dans un script.

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

2. Chemin du point de terminaison

Tous les appels passent par l'interface HiAPI unifiée. L'identifiant de modèle que vous ciblez est kling-4.0-flash/image-to-video. Votre requête de soumission et les interrogations d'état suivantes pointent vers le même espace de noms de modèle, donc placez cet identifiant dans une constante de votre code plutôt que de disperser des littéraux de chaîne partout.

3. Image de première frame prête

Vous avez besoin d'une image comme frame d'ouverture. Avant de l'envoyer, déterminez deux choses :

  • Comment la transmettre — sous forme d'URL accessible publiquement ou de données d'image encodées, selon la forme que ce point de terminaison accepte dans votre cas d'usage.
  • Si elle est bien formée — au bon format, lisible, et pas assez volumineuse pour alourdir le corps de la requête.

Règle pratique : gardez le corps de requête petit et explicite. Si vous transmettez une URL, assurez-vous que l'appelant peut y accéder sans authentification. Si vous transmettez des données encodées, vérifiez que l'encodage est exactement celui attendu par le point de terminaison.

Préparez également un prompt court et précis. Les prompts image-to-video fonctionnent mieux lorsqu'ils décrivent le mouvement et le changement (ce qui bouge, comment la caméra se déplace) plutôt que de reformuler ce qui est déjà visible dans la frame.

Requête curl fonctionnelle

Voici un appel de soumission complet. Remplacez les espaces réservés par votre propre clé, votre image et votre prompt.

curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Slow dolly-in on the subject as light shifts across the scene",
    "image": "https://your-host.example/first-frame.jpg"
  }'

Explication élément par élément :

  • -X POST — la soumission est une opération d'écriture, pas une requête.
  • URL — l'identifiant de modèle fait partie du chemin du point de terminaison unifié. C'est le seul endroit où vous spécifiez le modèle.
  • Authorization: Bearer $HIAPI_API_KEY — un en-tête développé par le shell à partir de votre variable d'environnement. Les guillemets doubles permettent l'expansion de la variable tout en gardant sa valeur comme un seul argument.
  • Content-Type: application/json — le corps est du JSON ; sans cet en-tête, certaines passerelles rejettent ou analysent mal la charge utile.
  • -d '{ ... }' — le corps JSON. prompt décrit le mouvement ; image fournit la première frame. Chaque champ est explicite — rien ne dépend implicitement de la position ou de valeurs par défaut invisibles.

Une soumission réussie renvoie un corps JSON contenant un identifiant de tâche. Capturez-le — cette valeur est votre handle pour manipuler la tâche. Si vous explorez de manière interactive, vous pouvez passer la réponse dans un outil de formatage JSON afin de copier l'identifiant :

curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool

Ne croyez pas que la vidéo se trouve dans cette réponse. Elle n'y est pas — cette réponse vous indique seulement que la tâche a été acceptée.

La même requête en Python

Le client Python correspond exactement à la charge utile curl. Changer de langage ne change pas la sémantique, seulement le mécanisme d'envoi des octets. Utilisez requests et lisez la clé depuis une variable d'environnement :

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"

def submit_job(prompt: str, image: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/{MODEL}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "image": image,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

job = submit_job(
    prompt="Slow dolly-in on the subject as light shifts across the scene",
    image="https://your-host.example/first-frame.jpg",
)
print(job)

Points clés du portage :

  • Utilisez json= au lieu de -d — passer un dict laisse requests sérialiser le corps et définir le type de contenu. Vous obtenez le même format sur le réseau que l'exemple curl, sans écrire le JSON à la main.
  • raise_for_status() — convertit les réponses non 2xx en exceptions, afin de ne pas prendre un corps d'erreur pour une référence de tâche.
  • timeout=30 — la soumission doit être rapide. Un délai d'attente relativement large évite les connexions bloquées sans masquer un appel réellement lent.
  • Un seul modèle constant — si vous changez de modèle plus tard, une seule ligne à modifier.

Le dict renvoyé contient l'identifiant de tâche, qui sera exploité dans la section suivante.

Gérer le cycle de vie d'une tâche asynchrone

Le schéma d'intégration est soumettre, puis interroger. Deux phases, clairement délimitées.

Phase 1 : soumettre et capturer la référence

L'appel submit_job de la section précédente renvoie un corps JSON contenant un identifiant de tâche. Conservez-le. Chaque vérification d'état ultérieure en a besoin ; le perdre revient à perdre la tâche.

Phase 2 : interroger jusqu'à l'état terminal

La vérification d'état est une requête de lecture sur la même tâche. Répétez à intervalle fixe jusqu'à ce que la tâche atteigne un état terminal — succès ou échec. Une boucle simple avec un nombre maximal de tentatives :

import time

def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/{MODEL}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()

        state = status.get("status")
        if state in ("succeeded", "failed"):
            return status
        time.sleep(interval)

    raise TimeoutError(f"Job {task_id} did not finish in time")

Décisions de conception à prendre délibérément :

  • Limitez le nombre d'itérations. N'interrogez jamais indéfiniment. Un nombre maximal de tentatives avec un intervalle fixe donne une attente maximale prévisible.
  • Dormez entre les vérifications, pas à l'intérieur de la requête. Une interrogation trop fréquente gaspille du quota et peut déclencher des limitations de débit.
  • Traitez l'échec comme un état terminal. Une tâche en échec ne deviendra pas un succès à la prochaine interrogation — arrêtez et exposez l'erreur.
  • Distinguez l'attente de la fin. Seul un état terminal termine la boucle ; tout autre état signifie qu'il faut continuer d'attendre.
  • Persistez l'ID de tâche. Si le processus plante en cours d'interrogation, vous voulez pouvoir reprendre plutôt que régénérer.

En production, déplacez l'interrogation hors du thread de requête — confiez-la à un worker en arrière-plan ou à un consommateur de file — afin qu'une génération longue ne maintienne pas une requête web ouverte.

Utiliser l'option audio synchrone

Ce point de terminaison propose une option audio synchrone. En pratique, cela signifie une chose pour le client : si vous l'activez, l'appel sera bloquant jusqu'à la fin de la génération, au lieu de renvoyer une référence de tâche à interroger.

Cela change votre conception de manière concrète :

  • Le budget de délai d'attente doit augmenter. Un appel de génération bloquant peut prendre beaucoup plus de temps qu'une requête API typique. Réglez le délai d'attente du client pour couvrir toute la durée prévue, pas la durée de soumission.
  • Pas de point de reprise en cours de route. Avec l'interrogation, vous pouvez planter et reprendre grâce à l'ID de tâche. Avec un appel bloquant, une connexion interrompue signifie refaire le travail.
  • Pression sur les threads et le pool de connexions. Un appel bloquant occupe un worker pendant toute sa durée. Dans un serveur web, cela limite rapidement votre capacité de concurrence.

Quand un appel bloquant est-il acceptable ? Lorsque vous exécutez un script ponctuel, un outil CLI ou une tâche par lots, que rien d'autre n'attend le résultat et que la simplicité prime sur le débit. Dans ces scénarios, l'appel synchrone supprime entièrement le mécanisme d'interrogation et le code est plus court.

Quand l'éviter ? Dans tout chemin de requête orienté utilisateur, dans les services à forte concurrence, ou partout où le client peut expirer et réessayer — un appel bloquant réessayé peut doubler votre charge de travail. Dans ces scénarios, conservez le modèle soumettre puis interroger de la section précédente, avec l'option synchrone désactivée.

Diagnostiquer les échecs courants

Traitez les échecs par couches. La première erreur que vous voyez est généralement la plus superficielle, donc corrigez-la et relancez, au lieu de deviner plusieurs problèmes à la fois.

Erreurs d'authentification

Un 401 ou 403 signifie que les identifiants sont manquants, mal formés ou rejetés. Vérifiez que HIAPI_API_KEY est bien définie dans l'environnement vu par votre processus — une variable exportée dans un shell ne se propage pas à un autre shell ou conteneur. Confirmez que l'en-tête Authorization est Bearer <key>, avec un seul espace et sans guillemets parasites issus d'un copier-coller.

Corps de requête mal formé

Un 400 signifie généralement que le corps ne peut pas être analysé ou qu'il manque des champs obligatoires. Vérifiez que vous envoyez Content-Type: application/json, que le JSON est valide (une virgule finale le fait échouer), et que prompt et image sont tous deux présents et non vides. Pour le débogage, affichez le corps réellement envoyé — pas le dict que vous comptiez envoyer.

Problèmes d'entrée image

Ces problèmes se manifestent souvent par des erreurs de validation, pas par une erreur d'image explicite. Vérifiez dans l'ordre :

  • Accessibilité — si vous transmettez une URL, récupérez-la depuis le même environnement réseau que la requête. Une URL qui fonctionne dans un navigateur peut être bloquée par un pare-feu ou protégée par authentification pour l'API.
  • Format — assurez-vous que l'image est un fichier pris en charge et non corrompu. En cas de doute, réexportez-la.
  • Taille — une image trop volumineuse peut provoquer un échec de validation ou gonfler le corps au-delà des limites.
  • Encodage — si vous envoyez des données encodées, vérifiez exactement que l'encodage correspond à ce qu'attend le point de terminaison ; un préfixe incompatible ou des espaces superflus provoquent l'échec.

Échecs au niveau de la tâche

Si la soumission réussit mais que la tâche se termine en échec, la requête est bien formée mais la génération n'a pas abouti. Relisez le prompt, vérifiez s'il y a ambiguïté ou mouvement physiquement irréaliste, et confirmez que l'image de première frame peut réellement servir de point de départ. Réessayez une fois avec un prompt simplifié avant de supposer un problème systémique — et consignez l'ID de tâche et le message d'échec pour pouvoir les corréler plus tard.

Expiration de la boucle d'interrogation

Le TimeoutError levé par wait_for_job signifie que vos limites sont trop serrées, pas que la tâche est morte. Augmentez le nombre de tentatives ou l'intervalle, et vérifiez que vous n'interrogez pas un ID de tâche d'une exécution antérieure déjà terminée.

Commencez par une requête minimale — une image, un prompt court, aucun champ optionnel — et n'ajoutez de la complexité qu'une fois la base fonctionnelle. La plupart des problèmes d'intégration disparaissent lorsque la charge utile est petite et explicite.

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