Comment appeler kling-4.0/image-to-video sur HiAPI : curl, Python et interrogation périodique

Ce que fait le point de terminaison kling-4.0/image-to-video

kling-4.0/image-to-video transforme une seule image statique en une courte vidéo générée. Sur HiAPI, il est exposé comme un point de terminaison basé sur des tâches : vous soumettez une image et une description de style invite précisant comment vous souhaitez que la scène bouge, et l'API renvoie immédiatement un identifiant de tâche plutôt que la vidéo finale terminée.

Au niveau de la requête, l'appelant doit fournir :

• l'identifiant du modèle (kling-4.0/image-to-video),
• l'image source (généralement une URL d'image accessible publiquement),
• une description textuelle qui guide le mouvement de l'image, ou ce qui doit se produire dans la scène,
• toutes les options de génération supplémentaires documentées par ce point de terminaison pour ce modèle.

Ce qui est renvoyé n'est pas la vidéo elle-même. La réponse de soumission porte un identifiant de tâche et un état initial. Le véritable clip vidéo ne devient disponible qu'une fois la tâche de génération terminée, et vous le récupérez alors en référençant cet identifiant.

Cette séparation constitue le modèle mental complet de ce point de terminaison : soumettre → obtenir l'id de tâche → interroger l'état → télécharger le résultat. Chaque section ci-dessous est une variante de ce cycle.

Comme le point de terminaison est asynchrone, votre code d'intégration a deux responsabilités plutôt qu'une : il doit envoyer une requête de soumission correctement formée et gérer la suite jusqu'à ce que la tâche atteigne un état terminal. Une fois ces deux points maîtrisés, il ne reste que le travail d'articulation habituel.

Prérequis et authentification

Avant tout appel, il vous faut deux choses : un compte HiAPI disposant de l'accès à ce modèle, et une clé API émise depuis la console.

L'authentification se fait par requête. Chaque appel à l'API inclut votre clé dans un en-tête HTTP — le schéma standard est un en-tête d'autorisation de style bearer :

Authorization: Bearer <YOUR_HIAPI_API_KEY>

Ne laissez pas la clé entrer dans un système de gestion de code source. Les pratiques habituelles sont les suivantes :

• Stockez-la dans une variable d'environnement (par exemple HIAPI_API_KEY) et lisez-la à l'exécution.
• Ne la collez jamais dans du code client, ni dans une commande curl que vous validerez ensuite dans un dépôt.
• Si la clé fuite, renouvelez-la depuis la console.

Exportez-la dans le shell afin que les exemples curl et Python ci-dessous puissent la lire :

export HIAPI_API_KEY="your-key-here"

Vous avez également besoin d'une URL d'image accessible. Le point de terminaison utilise l'image par référence, donc un chemin de fichier local sur votre ordinateur portable ne convient pas — hébergez l'image à un emplacement disposant d'une URL HTTPS stable, ou, si la plateforme propose un mécanisme de ressources, téléversez l'image et utilisez la référence renvoyée.

Une fois la clé exportée et l'image accessible, vous pouvez soumettre la tâche.

Décomposition pas à pas de la requête curl

Une requête de soumission complète se présente ainsi :

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "A slow camera push-in as the subject turns toward the light; soft afternoon shadows"
    }
  }'

Décryptage partie par partie :

• -X POST — la création de tâche se fait par POST, pas par GET. La requête porte un corps qui décrit le travail.
• URL — le point de terminaison de tâches unifié de HiAPI. Pour les modèles basés sur des tâches, c'est la même route ; le modèle est choisi dans le corps, pas dans le chemin.
• Authorization — votre clé, comme décrit dans la section précédente.
• Content-Type: application/json — le corps est du JSON ; omettre cet en-tête ou le mal orthographier fait généralement rejeter la requête par le serveur avant même qu'elle n'atteigne le modèle.
• model — la chaîne littérale kling-4.0/image-to-video. Considérez-la comme exacte et sensible à la casse ; une faute de frappe produit une erreur de modèle introuvable plutôt qu'un message utile.
• input.image — l'image statique source, fournie sous forme d'URL. C'est l'image que le modèle va animer, alors choisissez une image nette et bien composée.
• input.prompt — l'instruction en langage naturel. Décrivez le mouvement et le comportement de la caméra (avancée, panoramique, déplacement du sujet) ainsi que l'ambiance générale. Une invite vague produit un mouvement vague.

La réponse immédiate est un objet tâche, pas une vidéo. Il contient l'identifiant de la tâche et un champ d'état — généralement quelque chose comme en file d'attente ou en attente après la soumission. Conservez cet identifiant ; c'est la seule information dont vous aurez besoin pour vérifier la tâche ensuite.

À ce stade, le clip vidéo n'existe pas encore. C'est le comportement attendu, et la section suivante montre comment le gérer.

Le même appel en Python

La version Python fait exactement la même chose — même point de terminaison, mêmes en-têtes, même corps — donc l'outil choisi ne change pas le protocole.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "A slow camera push-in as the subject turns toward the light; "
                  "soft afternoon shadows",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Quelques points à surveiller en pratique :

• Utilisez json=payload plutôt que de sérialiser manuellement une chaîne. Cela définit le content-type pour vous et évite les erreurs de guillemets.
• Placez la requête de soumission et les opérations suivantes dans la même fonction ou classe, afin que l'id de tâche ne se perde pas entre les étapes.
• Définissez un délai d'expiration explicite. L'appel de soumission doit revenir rapidement ; il ne fait que créer la tâche, il n'attend pas la vidéo.
• N'appelez pas raise_for_status() puis ne supposez pas que la tâche existe — une réponse non-2xx signifie qu'aucune tâche n'a été créée, et le corps de l'erreur indique généralement quel champ est incorrect.

Si vous construisez un service, encapsulez cet appel dans un petit client, avec une méthode pour soumettre et une méthode pour vérifier l'état. Cela centralise les nouvelles tentatives, la journalisation et la gestion des clés en un seul endroit plutôt que de les disperser aux points d'appel.

Interroger une tâche asynchrone jusqu'à son achèvement

La génération image-vers-vidéo prend sensiblement plus de temps qu'une complétion de chat — le modèle doit synthétiser de nombreuses images, les encoder et stocker le résultat. Il est impossible de renvoyer le clip sans garder la connexion ouverte longtemps dans la réponse de soumission, c'est pourquoi ce point de terminaison est asynchrone par conception.

Comment vérifier l'état

Interrogez la tâche par identifiant avec une requête GET :

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

La réponse décrit la tâche : son état et, une fois terminée, sa sortie. L'état passe généralement d'un état en file d'attente à un état en cours d'exécution, puis à un état terminal — par exemple réussi, ou échoué avec un message d'erreur.

Boucle d'interrogation simple en Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # gentle backoff, capped

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

Conseils sur la temporisation

• Commencez par un intervalle court et augmentez-le progressivement. La génération ne se termine pas à la première seconde, donc interroger fréquemment le point de terminaison ne fait que gaspiller du quota et déclencher la limitation de débit.
• Plafonnez l'intervalle afin de remarquer rapidement les tâches terminées — quelques secondes suffisent en régime stable.
• Définissez toujours une échéance stricte. Sans limite, une tâche qui ne se termine jamais est indiscernable d'une tâche exceptionnellement longue.
• Interrogez depuis un processus en arrière-plan ou une tâche planifiée, plutôt que de bloquer une requête web. Si un utilisateur attend dans l'interface, faites interroger votre propre point de terminaison d'état par le frontend.
• Réessayez en cas d'erreurs réseau transitoires lors des appels d'état, mais ne réessayez pas une tâche déjà signalée comme failed — la bonne action est alors de soumettre une nouvelle tâche.

Récupérer et stocker le clip vidéo renvoyé

Lorsque l'interrogation renvoie un état terminal de succès, l'objet tâche contient une référence de sortie vers la vidéo générée — une URL de ressource ou une référence équivalente pointant vers la vidéo terminée.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Deux décisions de conception se posent généralement ici.

Téléchargez rapidement. Les URL de sortie ont souvent une durée de validité limitée. Si vous comptez conserver le clip, copiez-le dans votre propre stockage plutôt que de remettre l'URL brute à l'utilisateur en espérant qu'elle reste valide.

Stockez les métadonnées avec le fichier. Conservez durablement l'id de tâche, l'invite, la référence de l'image source et l'horodatage de création avec la vidéo. Si quelqu'un demande plus tard pourquoi le clip ressemble à cela, cet enregistrement est la réponse.

Pour la fourniture de service, le schéma courant est le suivant : générer côté backend, stocker le fichier dans un stockage objet et renvoyer au client votre propre URL stable. Votre application contrôle ainsi l'accès, l'expiration et la mise en cache, au lieu de dépendre du cycle de vie de la ressource générée.

Si vous souhaitez régénérer avec un mouvement différent, soumettez une nouvelle tâche avec une invite ajustée — chaque tâche est indépendante et il n'est pas nécessaire de modifier une tâche déjà terminée.

Diagnostiquer les requêtes échouées

En cas de problème, partez de la structure de la requête et élargissez progressivement. La plupart des échecs se résument à quelques causes.

L'appel de soumission renvoie une erreur

• Chaîne de modèle incorrecte. kling-4.0/image-to-video doit correspondre exactement, y compris la casse et la barre oblique. Affichez la chaîne que vous envoyez réellement, plutôt que de faire confiance au fichier source.
• Authentification refusée. Vérifiez que l'en-tête est bien Authorization: Bearer <key> — pas la clé brute, pas un paramètre de requête — et que la variable d'environnement est définie dans le même shell ou processus qui exécute la requête.
• Image inaccessible. L'image doit être récupérable par la plateforme via HTTPS. Les URL localhost, les buckets privés ou les hôtes protégés contre le hotlinking échoueront. Ouvrez l'URL dans une fenêtre de navigation privée pour vérifier qu'elle se résout sans authentification.
• Champ manquant ou mal nommé. Le corps imbrique les entrées du modèle sous input. Placer prompt ou image au niveau supérieur plutôt qu'à l'intérieur de input est une erreur courante ; l'erreur de validation indique généralement le nom du champ.
• Type de contenu. Envoyer un corps JSON sans Content-Type: application/json est rejeté avant même d'impliquer le modèle.

La tâche a été créée mais n'a jamais réussi

• Trop peu d'interrogations ou aucune. Vérifiez que votre boucle s'exécute réellement et que les valeurs d'état qu'elle compare correspondent à celles renvoyées par l'API. Une faute de frappe dans la vérification de l'état terminal provoque une boucle infinie.
• La tâche passe à failed. Lisez le message d'erreur dans l'objet tâche ; il pointe généralement vers l'entrée — par exemple une image impossible à décoder.
• Vous avez atteint l'échéance. Si la tâche est encore en cours d'exécution près du délai d'expiration, augmentez la limite plutôt que de resoumettre en boucle, ce qui ne ferait qu'accroître la charge et le coût.
• Le lien de sortie a expiré. Si la tâche réussit mais que le téléchargement renvoie 404, trop de temps s'est écoulé entre l'achèvement et la récupération. Téléchargez immédiatement après le succès.

Une habitude de diagnostic rapide : lors des premières intégrations, journalisez mot pour mot le corps de la réponse de soumission. Il vous indiquera l'id de tâche, l'état initial et les noms de champs exacts renvoyés par ce point de terminaison, ce qui élimine les conjectures lors de chaque échec ultérieur.