Blog

Tutoriel

Comment utiliser kling-3.0/motion-control via l'API HiAPI : exemples en curl et Python

Nov 12, 2026
Image de couverture : une large bande de lumière ambrée balaie en diagonale un fond charbon chaud, aux bords nets, avec quelques formes géométriques sombres en dessous.
Sur cette page

À quoi sert kling-3.0/motion-control et quand l'utiliser

Le contrôle du mouvement est une capacité de génération vidéo : vous fournissez une vidéo de référence au modèle, et c'est elle qui pilote le mouvement, le rythme et la composition de la sortie, plutôt qu'une simple description textuelle de l'action. Avec kling-3.0/motion-control sur l'API HiAPI, la vidéo de référence est l'entrée principale : elle ancre la manière dont les objets se déplacent, et les autres paramètres façonnent le contenu généré autour de ce mouvement.

Choisissez ce modèle lorsque le mouvement lui-même est la difficulté. Scénarios typiques adaptés :

  • Vous avez une courte vidéo et souhaitez reproduire son mouvement de caméra ou l'action de son sujet avec un contenu différent.
  • Vous avez besoin d'un mouvement prévisible, plutôt que de résultats de génération texte-vers-vidéo obtenus au hasard via des prompts textuels.
  • Vous construisez un pipeline dans lequel le mouvement est un actif réutilisable d'une génération à l'autre, et doit donc être fourni en entrée plutôt que décrit par une phrase.

Si vous avez seulement besoin de génération texte-vers-vidéo, sans référence de mouvement, le contrôle du mouvement n'ajoutera qu'une étape de téléversement et des contraintes d'entrée plus strictes, sans bénéfice. De même, si la vidéo de référence est longue ou que sa composition est instable, attendez-vous à davantage de tentatives. Le reste de ce guide suppose que vous avez déterminé que le contrôle du mouvement est l'outil adéquat et que vous souhaitez une intégration fiable et reproductible.

Prérequis et configuration des points de terminaison

Avant le premier appel, préparez trois éléments.

1. Clé API

Créez une clé dans la console de votre compte HiAPI.ai et stockez-la dans une variable d'environnement, plutôt que de l'écrire dans le code source :

export HIAPI_API_KEY="your_api_key_here"

Envoyez-la comme jeton bearer dans chaque requête : Authorization: Bearer $HIAPI_API_KEY.

2. Convention d'URL de base

Tous les appels HiAPI partagent la même URL de base et le même préfixe de chemin versionné. Placez l'URL de base dans votre configuration afin de changer d'environnement sans modifier les points d'appel :

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. Identifiant de modèle

Le modèle est sélectionné requête par requête via le champ model de la requête, avec l'identifiant exact kling-3.0/motion-control. Ne le codez pas en dur à plusieurs endroits : passez-le comme constante, ainsi un futur changement de modèle ne nécessitera qu'une seule ligne modifiée.

Vous avez également besoin d'un emplacement d'hébergement à partir duquel l'API peut récupérer la vidéo de référence. La pratique courante est d'utiliser une URL signée à durée limitée ; assurez-vous qu'elle est accessible sans en-têtes personnalisés ni cookie.

Une fois ces trois éléments prêts, il ne reste que la structure de la requête et le cycle de vie de la tâche.

Fournir la vidéo de référence et les paramètres de mouvement

Une requête de contrôle du mouvement se divise conceptuellement en deux parties : la source du mouvement (votre vidéo de référence) et les paramètres de génération (ce que le modèle doit produire).

Vidéo de référence

La vidéo de référence est placée dans le corps de la requête sous forme d'URL, et non en octets bruts dans la charge JSON. Deux règles pratiques :

  • Utilisez une URL valide pendant toute la durée de mise en file et de traitement de la tâche. Une URL signée qui expire trop tôt est une cause fréquente d'échec des tâches quelques minutes après la soumission.
  • Gardez la vidéo courte et visuellement stable. Un matériel de référence trop long, très tremblant ou fréquemment coupé donne au modèle un signal de mouvement ambigu.

Si le matériel est stocké dans un stockage privé, générez l'URL signée au moment de la soumission, avec une durée de validité suffisante, et non au moment du téléversement.

Paramètres de mouvement et de sortie

Paramètres généralement définis avec la vidéo de référence :

  • Un prompt textuel décrivant le contenu cible, qui doit être animé par le mouvement de référence.
  • Les réglages de rapport d'aspect et de durée de sortie, afin que la vidéo générée corresponde à votre emplacement d'affichage.
  • Tout réglage d'intensité ou de fidélité du mouvement exposé par le modèle, pour arbitrer entre fidélité à la référence et liberté du prompt.

Regroupez ces paramètres dans un petit objet de configuration explicite côté client, plutôt que de les disperser dans les arguments de fonction. Cela permet de tracer précisément ce qui a été soumis, ce qui constitue le matériel de débogage le plus utile pour ce modèle.

Enfin, validez avant de soumettre : l'URL de référence renvoie un type de contenu média, le prompt n'est pas vide, et toutes les valeurs numériques sont dans les plages documentées. Une vérification locale ne coûte que quelques millisecondes ; une tâche asynchrone rejetée coûte un aller-retour et de la confusion.

Tâches asynchrones : soumettre, sonder et lire le résultat

Le contrôle du mouvement ne renvoie pas de vidéo dans la réponse de soumission, mais une tâche que vous devez suivre. Construisez votre client autour de ce cycle de vie dès le départ.

Étape 1 — Soumettre

Envoyez la tâche par POST au point de terminaison du modèle. Une soumission réussie renvoie un identifiant de tâche. Persistez immédiatement cet ID : c'est votre seul identifiant pour manipuler la tâche, utilisé lors du sondage et des demandes de support.

Étape 2 — Sonder

Récupérez l'état de la tâche par GET avec cet ID. Le champ de statut vous indique l'une des trois situations :

  • En attente ou en file : acceptée, pas encore démarrée. Continuez d'attendre.
  • En traitement ou en cours : en cours d'exécution. Continuez d'attendre, mais avec une stratégie de backoff.
  • État terminal : succès ou échec. Arrêtez le sondage.

La boucle de sondage doit vérifier explicitement les états terminaux, et pas seulement la présence du champ de sortie. Une tâche échouée n'a pas de résultat, et traiter « aucun résultat pour l'instant » comme « toujours en cours » conduit à une boucle infinie.

Étape 3 — Lire le résultat

En cas de succès, la réponse contient l'emplacement de la sortie, généralement l'URL de la vidéo générée. Téléchargez-la rapidement dans votre propre stockage : un actif généré derrière une URL temporaire ne doit pas être considéré comme disponible en permanence.

Bonnes pratiques de sondage

Deux règles le rendent fiable en production :

  1. Appliquez un backoff entre les sondages (commencez par une ou deux secondes, puis augmentez) au lieu de marteler le point de terminaison.
  2. Limitez le temps d'attente total et exposez le dépassement comme une erreur réessayable, plutôt que de bloquer indéfiniment un thread de travail.

Enregistrez l'ID de tâche, les paramètres soumis et l'état final pour chaque exécution. En cas d'anomalie, ce journal répond à la plupart des questions avant même que vous ne demandiez à quelqu'un d'autre.

Requête curl exécutable

Voici le flux complet dans un shell. Il soumet la tâche, extrait l'ID de tâche, puis sonde jusqu'à ce que la tâche atteigne un état terminal.

#!/usr/bin/env bash
set -euo pipefail

BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"

# 1) Soumettre la tâche
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "prompt": "Un bateau en papier dérive dans une rue urbaine sous la pluie, rendu cinématographique",
    "reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
    "duration": 5,
    "aspect_ratio": "16:9"
  }')

echo "$SUBMIT"

TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"

# 2) Sonder jusqu'à l'état terminal
while true; do
  STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
  echo "status: $STATUS"

  case "$STATUS" in
    succeeded) echo "$STATUS_JSON"; break ;;
    failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
  esac

  sleep 3
done

Deux remarques pour adapter ce script. Premièrement, conservez l'identifiant de modèle et le chemin du point de terminaison dans des variables pour garder le script lisible. Deuxièmement, l'analyse ci-dessus n'utilise pas jq, seulement Python, car Python est disponible presque partout ; si vous préférez jq, vous pouvez le remplacer. Dans les deux cas, le comportement clé est identique : extraire l'ID de tâche de la réponse de soumission, puis sonder son état jusqu'à voir une valeur terminale.

La même requête (version Python)

Le client Python ci-dessous correspond au flux curl, mais avec une boucle de sondage plus robuste : backoff approximativement exponentiel, délai global et traitement explicite de chaque état terminal.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"

HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

TERMINAL = {"succeeded", "failed", "cancelled"}


def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "reference_video_url": reference_video_url,
        "duration": duration,
        "aspect_ratio": "16:9",
    }
    r = requests.post(
        f"{BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["id"]


def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/videos/generations/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in TERMINAL:
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = submit_job(
        prompt="Un bateau en papier dérive dans une rue urbaine sous la pluie, rendu cinématographique",
        reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
    )
    print("submitted:", task_id)
    result = wait_for_job(task_id)

    if result["status"] == "succeeded":
        print("output:", result.get("output"))
    else:
        print("job did not succeed:", result)

Éléments à conserver lors de l'adaptation : l'ensemble des états terminaux, le backoff plafonné, et la séparation des fonctions de soumission et d'attente. Dans un vrai service, vous les répartirez entre deux processus — soumission depuis le gestionnaire de requêtes, stockage de l'ID de tâche, sondage par un worker — afin qu'une tâche lente ne bloque jamais la réponse HTTP.

Points de défaillance courants et méthodes de débogage

La plupart des problèmes d'intégration de kling-3.0/motion-control se répartissent en quelques catégories. Vérifiez-les dans l'ordre.

Erreurs d'authentification et de modèle

Une 401 signifie presque toujours que le jeton bearer est manquant, tronqué, ou provient du mauvais environnement. Une erreur de modèle introuvable signifie que la chaîne model ne correspond pas exactement — c'est un identifiant séparé par une barre oblique, donc un ordre de caractères erroné ou un espace superflu échouera silencieusement dans la configuration, mais bruyamment au niveau de l'API.

Vidéo de référence indisponible

La tâche est acceptée, puis échoue quelques minutes plus tard parce que l'URL de référence n'a pas pu être récupérée. Causes par ordre de fréquence : l'URL signée expire avant le traitement ; l'URL exige un en-tête d'authentification que le service n'envoie pas ; l'URL renvoie du HTML (page de connexion ou page d'erreur) au lieu d'une vidéo. Testez l'URL avec un simple curl depuis l'extérieur de votre réseau et vérifiez le type de contenu.

Erreurs de format ou de plage de paramètres

Des réglages de durée et de rapport d'aspect hors des plages documentées sont rejetés à la soumission, ce qui est une bonne chose — vous obtenez l'erreur immédiatement. Validez localement au préalable, afin qu'une faute de frappe ne nécessite pas un aller-retour pour être découverte.

Défauts de sondage

Deux problèmes classiques : une boucle qui vérifie seulement le champ de sortie et jamais failed, provoquant une boucle infinie ; et un sondage dans une boucle serrée sans pause, provoquant votre propre limitation de débit. Ajoutez des vérifications explicites des états terminaux et un backoff, et joignez toujours l'ID de tâche dans les rapports d'erreur afin d'interroger la tâche plutôt que de la reconstruire.

URL de résultat expirée

Vous avez généré la vidéo, mais n'avez enregistré que l'URL de sortie temporaire. Téléchargez la sortie dans votre propre stockage dès que la tâche réussit ; considérez l'URL renvoyée comme un identifiant de récupération, pas comme un stockage persistant.

Commencez chaque session de débogage par enregistrer le corps exact de la requête et la réponse JSON brute. Presque tous les problèmes ci-dessus sont visibles dans ces deux éléments. Lorsque vous voudrez aller plus loin, consultez les autres modèles vidéo et la référence des points de terminaison dans la documentation HiAPI.ai, et conservez la même forme de client « soumettre d'abord, sonder ensuite ».

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