Comment réaliser une courte vidéo avec kling-3.0/motion-control sur l'API hiapi

Si vous avez déjà essayé de faire exécuter à un personnage dans une vidéo générée un mouvement précis — pas « danser », mais cette danse précise dans cet extrait précis — vous savez que les options habituelles sont mauvaises : rotoscopie à la main image par image, réentraînement d'un modèle de mouvement, ou abandon pur et simple en acceptant ce que le prompt textuel vous donne. kling-3.0/motion-control évite tout cela. Vous lui donnez une image de personnage et une vidéo de référence, et il transfère le mouvement et les expressions de la référence sur votre personnage — sans rigging squelettique, sans images clés, sans combinaison de captation de mouvement.

Cet article parcourt un véritable flux de travail pour vidéos courtes : d'abord, transformer la photo d'un chauffeur en un court extrait de référence, puis utiliser cet extrait pour piloter via motion-control l'image d'un personnage totalement différent. Chaque requête ci-dessous est un appel réel à l'API /v1/tasks de hiapi, chaque élément a été généré pendant la rédaction de cet article (rien n'a été emprunté à une galerie de démonstration d'un fournisseur), et chaque prix a été récupéré en temps réel depuis le point de terminaison de tarification de hiapi.

Ce que fait réellement kling-3.0/motion-control

Le modèle prend deux entrées :

• image_url — un portrait unique de personnage (la « cible »). C'est ce qui détermine qui apparaît dans la sortie.
• video_url — l'extrait de référence de mouvement, de 3 à 30 secondes. C'est ce qui détermine ce qu'il fait.

La sortie est une vidéo du personnage cible exécutant les mouvements et expressions faciales de la vidéo de référence, rendue en 720p ou 1080p. Elle n'accepte pas de prompt textuel, de durée ni de ratio d'aspect — la composition de la sortie suit directement l'extrait de référence, et la longueur de la sortie suit également la longueur de l'extrait d'entrée (notre référence de 3 secondes a produit une sortie de 3,03 secondes).

Ce contrat étroit à deux entrées est précisément ce qui le rend utile pour le contenu court : vous n'avez pas besoin d'un équipement de captation de mouvement pour faire jouer de manière crédible une mascotte de marque, un personnage de produit ou un avatar stylisé — vous avez seulement besoin d'n'importe quel extrait vidéo d'un humain exécutant le mouvement souhaité.

Ce dont vous avez besoin

• Une clé API hiapi (Authorization: Bearer <key>)
• Une image de personnage accessible publiquement via HTTPS (pas votre cible — votre personnage conducteur)
• Une seconde image de personnage, celle que vous voulez réellement animer
• ffmpeg/ffprobe si vous souhaitez extraire localement une image de couverture ou vérifier la durée d'un extrait, comme dans cet article

Démonstration réelle : un extrait de mouvement, deux personnages différents

L'essentiel de motion-control est que la vidéo de référence et le personnage final n'ont pas besoin de correspondre. Pour le prouver, cette démonstration utilise trois étapes de génération :

1. Un portrait de chauffeur, animé en un court extrait de référence :

Ce portrait a été transformé en un extrait de mouvement de 3 secondes en 480p via grok-imagine-1.5/image-to-video — une méthode rapide et économique pour fabriquer un extrait de référence à partir d'une image statique, plutôt que de chercher un extrait existant :

2. Un personnage cible complètement différent — même mouvement, apparence totalement différente :

3. Envoyer les deux à motion-control. Le vendeur exécute exactement le même mouvement de retournement et de regard en arrière que le coursier :

C'est tout le flux de travail : générez (ou procurez-vous) n'importe quel extrait de mouvement qui vous plaît, pointez motion-control vers une image de personnage totalement sans rapport, et obtenez ce personnage exécutant le mouvement. Pour un pipeline de vidéos courtes, cela signifie qu'une bibliothèque de mouvements de référence peut piloter un nombre infini de personnages, sans avoir à retourner ou à refaire l'animation de référence à chaque fois.

Requête minimale fonctionnelle (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

Réponse (tâche créée, toujours en cours de traitement) :

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

Interrogez jusqu'à la fin :

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Lors de notre exécution, un extrait de 3 secondes en 720p a pris environ 2,3 minutes du début à la fin (le statut a bouclé une douzaine de fois sur handling avant de passer à success) — prévoyez quelques minutes, et non quelques secondes, lors de la conception de votre boucle d'interrogation. Réponse finale :

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

Ce output[0].url est un lien temporaire — expireAt est un horodatage Unix, valable environ 24 heures dans notre test. Téléchargez-le et réhébergez-le immédiatement ; ne créez pas de lien direct vers celui-ci depuis quoi que ce soit que vous publiez.

Le même flux en Python

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

Rien de compliqué — créez la tâche, interrogez GET /v1/tasks/{taskId} à intervalles réguliers, téléchargez output[0].url dès que le statut passe à success, et réhébergez-la vous-même avant que le lien temporaire n'expire.

Les paramètres que motion-control valide réellement

Le schéma est strict — tout ce qui dépasse ces trois champs sera rejeté. Il est utile de le savoir à l'avance plutôt que de le découvrir par tâtonnements :

Champ	Obligatoire	Description
image_url	Oui	URL HTTPS publique, personnage cible
video_url	Oui	URL HTTPS publique, référence de mouvement de 3 à 30 secondes
resolution	Non (valeur par défaut, mais il vaut la peine de la définir)	"720p" ou "1080p" — détermine aussi le palier tarifaire

Les champs que vous pourriez attendre d'autres modèles vidéo — duration, aspect_ratio, prompt — sont rejetés avec une erreur de schéma :

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

C'est voulu : la longueur et la composition de la sortie héritent entièrement de la vidéo de référence, donc duration/aspect_ratio n'ont rien à contrôler. Si vous voulez une sortie plus longue ou avec une composition différente, recadrez ou recomposez l'extrait de référence avant l'envoi, plutôt que de modifier la requête.

Tarification : facturé à la seconde de sortie, pas à la requête

Directement depuis le point de terminaison de tarification de hiapi :

Résolution	Prix
720p	0,10 $ / seconde de sortie
1080p	0,172 $ / seconde de sortie

La facturation est pilotée par la durée réelle de sortie (estimated_seconds), qui reflète la longueur de votre extrait de référence — et non un coût fixe par requête. Notre référence de 3 secondes en 720p a produit une sortie de 3,03 secondes, pour un coût d'environ 0,30 $. Un extrait de référence de 10 secondes en 1080p approcherait 1,72 $. Si vous l'utilisez en volume dans un calendrier éditorial, le véritable levier ajustable est la longueur de l'extrait de référence : des extraits plus courts coûtent moins cher et portent tout de même une prestation de mouvement complète pour les formats courts (Reels, TikTok, Shorts), où 3 à 8 secondes constituent souvent l'intégralité de l'extrait.

Points d'attention pour la production

• Choisissez consciemment la composition de l'extrait conducteur. La sortie hérite du ratio d'aspect, de la distance de caméra et du rythme de la vidéo de référence — une référence en gros plan donnera une sortie en gros plan, quel que soit le recadrage de votre image de personnage cible.
• Les expressions nettes se transfèrent mieux que les subtiles. Un retournement, un salut ou une inclinaison de tête clairs dans la référence apparaissent de manière fiable sur le personnage cible ; les micro-expressions très fines et naturelles sont plus difficiles à identifier et à transférer pour le modèle.
• Réutilisez un extrait de référence pour de nombreux personnages. Comme video_url et image_url sont totalement indépendants, le schéma le plus efficace dans un pipeline de contenu est : constituer d'abord une petite bibliothèque de mouvements de référence, puis exécuter de nombreuses images de personnages différentes avec le même extrait.
• Les URL de sortie temporaires ont une courte durée de vie. expireAt correspond généralement à environ un jour — téléchargez et réhébergez immédiatement, plutôt que de planifier le téléchargement plus tard.
• Le traitement n'est pas instantané. Dans ce test, un extrait de 3 secondes en 720p a pris plus de deux minutes du début à la fin ; planifiez votre boucle d'interrogation et toute automatisation en aval en minutes (et non en secondes, comme pour les appels texte-image habituels).

Contenu associé

• Page du modèle kling-3.0/motion-control
• Tarification hiapi
• Documentation de l'API hiapi

Vous avez un extrait de référence et un personnage à associer ? Obtenez une clé depuis la page de tarification, puis pointez la requête curl ci-dessus vers vos propres image_url/video_url — toute la boucle ci-dessus est directement copiable-collable.

Questions fréquentes

Puis-je utiliser n'importe quelle vidéo comme référence de mouvement ? N'importe quelle vidéo avec un interprète humain (ou humanoïde) clair convient, du moment qu'elle est accessible publiquement via HTTPS et dure entre 3 et 30 secondes. Elle n'a pas besoin de contenir votre personnage cible — c'est tout l'intérêt de ce modèle.

La sortie conserve-t-elle l'arrière-plan de la vidéo de référence ? Non — l'apparence du personnage, y compris l'environnement suggéré par l'image cible, est conservée ; la vidéo de référence fournit les mouvements et les expressions, pas le contenu de la scène.

Pourquoi ma requête a-t-elle été rejetée avec « unexpected additional properties » ? Le schéma n'accepte que image_url, video_url et resolution. Des champs comme duration, aspect_ratio ou prompt ne font pas partie des entrées de ce modèle et renvoient immédiatement une erreur 400 — supprimez-les de la charge utile.

Combien de temps prend une tâche motion-control ? Prévoyez quelques minutes par extrait. Notre exemple de 3 secondes en 720p a pris environ 2,3 minutes entre la création de la tâche et la sortie success téléchargeable.

Puis-je contrôler la résolution de sortie indépendamment du prix ? Non — resolution est à la fois un réglage de qualité de sortie et un sélecteur de palier tarifaire : "720p" est facturé 0,10 $/seconde de sortie, "1080p" est facturé 0,172 $/seconde de sortie.