Démarrage rapide de l'API Kling V3.0 Motion Control

Kling V3.0 Motion Control vous permet d’animer une image de personnage statique en extrayant le mouvement d’une vidéo de référence et en l’appliquant image par image. Le résultat préserve l’apparence du personnage de votre image tout en reproduisant le mouvement de la vidéo — une technique appelée transfert de mouvement. Ce guide couvre l’endpoint Novita AI, les entrées requises, les paramètres clés et des exemples Python et curl fonctionnels que vous pouvez exécuter avec une vraie clé API.

Quand Motion Control est le bon outil

Motion Control est le bon outil lorsque vous disposez de deux éléments : une image de personnage statique que vous souhaitez animer, et une vidéo de référence dont vous voulez reproduire le mouvement. Cela diffère de l’Image-to-Video (I2V), qui génère le mouvement à partir d’un prompt. Avec Motion Control, le mouvement est copié précisément depuis la vidéo de référence — le personnage final suivra la même trajectoire de mouvement que la personne dans la vidéo de référence.

Utilisez-le lorsque :

• Vous souhaitez appliquer une danse, un cycle de marche ou un geste spécifique à une illustration ou une photo de personnage
• Vous avez besoin d’un mouvement cohérent et reproductible sur différents personnages (même vidéo de référence, images différentes)
• Vous créez du contenu où la qualité du mouvement compte et où les résultats I2V ouverts à partir d’un prompt sont trop imprévisibles

Ne l’utilisez pas lorsque le mouvement lui-même n’est pas encore défini — dans ce cas, l’I2V avec un prompt descriptif offre plus de flexibilité à moindre coût.

Étape 1 : Obtenir votre clé API Novita

Inscrivez-vous sur novita.ai et générez une clé API depuis le tableau de bord. Les nouveaux comptes reçoivent des crédits gratuits que vous pouvez utiliser pour tester Motion Control avant de passer à un volume de production.

Étape 2 : Vérifier l’endpoint et l’ID du modèle

Kling V3.0 Motion Control sur Novita AI utilise le modèle standard de vidéo asynchrone :

Soumettre la tâche :

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Interroger le résultat :

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

Toutes les requêtes nécessitent :

Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json

Documentation complète : novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Étape 3 : Préparer vos entrées

Motion Control nécessite deux entrées : une image de référence et une vidéo de référence. Bien les choisir est le facteur le plus important pour la qualité du résultat.

Image de référence

C’est le personnage dont l’apparence sera préservée dans le résultat. Exigences :

• Formats : JPEG, PNG, JPG
• Taille maximale : 10 Mo
• Résolution minimale : 340 px sur chaque côté
• Ratio d’aspect : entre 2:5 et 5:2
• Le personnage doit être clairement visible, occuper plus de 5 % de la surface de l’image et ne doit pas être fortement masqué (ne recadrez pas la tête ou le corps)

Pour de meilleurs résultats, utilisez une image où les proportions corporelles du personnage correspondent approximativement à ce qui est visible dans la vidéo de référence. Si la vidéo de référence montre un danseur en pied, utilisez une image du personnage en pied plutôt qu’un recadrage portrait.

Vidéo de référence

C’est la source du mouvement. Le personnage du résultat reproduira les mouvements de cette vidéo :

• Formats : MP4, MOV
• Taille maximale : 10 Mo
• Durée : 3 à 30 secondes
• Résolution minimale : 340 px sur chaque côté
• Ratio d’aspect : entre 2:5 et 5:2
• La personne dans la vidéo de référence doit avoir son corps entier ou le haut du corps visible et dégagé, y compris la tête

Des images claires, bien éclairées et avec un arrière-plan peu encombré transfèrent le mouvement plus précisément que des plans bruités ou surchargés.

Étape 4 : Envoyer votre première requête

Requête curl minimale :

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

La réponse renvoie un task_id immédiatement :

{
  "task_id": "abc123xyz"
}

Étape 5 : Interroger le résultat

Kling V3.0 Motion Control est asynchrone. Soumettez la tâche, puis interrogez jusqu’à ce que le statut soit succeed :

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

Une fois terminée, la réponse contient un tableau videos avec l’URL du résultat :

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

Le temps de génération typique est de 30 à 120 secondes selon la durée de la vidéo et le mode. Interrogez toutes les 5 à 10 secondes plutôt que de surcharger l’endpoint.

Exemple complet d’intégration Python

Ce script soumet une tâche Motion Control et interroge le serveur jusqu’à ce qu’elle soit terminée :

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

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

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

Référence des paramètres API

Paramètre	Type	Requis	Description
image	string	Oui	URL de l’image du personnage à animer. Voir les exigences d’entrée ci-dessus.
video	string	Oui	URL de la vidéo de référence dont le mouvement sera transféré.
model_name	string	Oui	Défini sur kling-v3.0-motion-control.
prompt	string	Non	Description textuelle du style de mouvement souhaité ou du contexte de la scène. Facultatif mais peut améliorer la qualité du résultat.
character_orientation	string	Non	Contrôle l’alignement de la pose et la durée de sortie. "video" correspond à l’orientation de la vidéo de référence — mieux pour les mouvements complexes du corps entier, prend en charge jusqu’à 30 s. "image" correspond à l’orientation de l’image du personnage — mieux pour les mouvements relatifs à la caméra, fixé à 5 s.

character_orientation en pratique

Si votre vidéo de référence montre un danseur de face et que votre image de personnage est également de face, "video" offrira un meilleur transfert de mouvement et prend en charge jusqu’à 30 secondes. Si la vidéo de référence a une caméra qui tourne autour du sujet et que votre image est un portrait à angle fixe, "image" tend à réduire les distorsions de perspective indésirables — mais notez qu’il génère un clip fixe de 5 secondes.

Standard vs Pro : quel niveau de qualité choisir

Kling V3.0 Motion Control est disponible en deux niveaux de qualité :

Standard génère en 720p. C’est le bon choix pour itérer, tester la compatibilité du mouvement ou générer des brouillons avant de vous engager sur une version finale.

Pro génère en 1080p avec une fidélité de mouvement et une cohérence du sujet améliorées. Utilisez Pro lorsque :

• Le résultat est destiné à une production finale (publication sur les réseaux sociaux, court-métrage, démo produit)
• Les détails fins du visage ou des vêtements du personnage comptent
• Vous générez des clips plus longs (10 s et plus) où la dégradation de la qualité au fil du temps est plus visible

Pour la plupart des flux de développement, commencez par Standard pour confirmer la compatibilité des entrées et la qualité du mouvement, puis passez à Pro pour la version finale.

Tarification, durée et estimation des coûts

Novita AI facture Motion Control à la seconde de vidéo générée. Les niveaux Standard et Pro ont des tarifs distincts par seconde. Pour la tarification actuelle, consultez la page du modèle Novita AI.

Limites de durée :

• character_orientation: "video" — jusqu’à 30 secondes
• character_orientation: "image" — fixé à 5 secondes

Le coût augmente avec la durée pour le mode "video". Le mode "image" génère toujours un clip de 5 secondes.

Dépannage des erreurs courantes

La tâche échoue immédiatement avec une erreur 422 ou une erreur de validation Vérifiez que image et video sont des URL accessibles publiquement (pas derrière une authentification ou une URL pré-signée à courte durée de vie qui a expiré). Le backend Novita doit pouvoir récupérer les deux fichiers au moment de l’exécution de la tâche.

Le mouvement du résultat semble incorrect ou le personnage se déforme La cause la plus courante est une inadéquation entre l’orientation du personnage dans l’image et celle de la vidéo de référence. Essayez de basculer character_orientation entre "video" et "image" pour voir lequel produit un meilleur alignement.

Le personnage perd son identité faciale en plein clip Assurez-vous que le personnage de l’image de référence a un visage et un corps clairs et non obstrués. Pour les clips plus longs, le niveau Pro maintient mieux la cohérence du sujet que Standard.

Le mouvement de la vidéo de référence ne se transfère pas correctement Des images de référence bruitées ou surchargées dégradent l’extraction du mouvement. Utilisez des images où l’interprète est le sujet principal sur un arrière-plan raisonnablement propre. Évitez les séquences tremblantes filmées à la main si l’objectif est un transfert de mouvement fluide.

Statut bloqué sur processing pendant plus de 3 minutes Des délais de file d’attente occasionnels se produisent. Attendez jusqu’à 5 minutes avant de considérer la tâche comme bloquée. Si elle reste bloquée, soumettez une nouvelle tâche — ne réutilisez pas l’ancien task_id.

Ce que les développeurs créent avec Kling Motion Control

Animation de personnages pour des assets de jeu : prenez une illustration de personnage et appliquez un clip de mouvement de référence (marche, course, attaque) sans logiciel de rigging ni d’animation.

Contenu social avec un mouvement cohérent : appliquez la même vidéo de référence de danse à plusieurs images de personnages pour produire une série de clips avec une chorégraphie identique mais des apparences différentes.

Prévisualisation : testez à quoi ressemble une séquence de mouvement spécifique sur un design de personnage avant d’investir dans une animation de production complète.

Affichage de produits e-commerce : appliquez des changements de pose subtils ou des mouvements de vêtements aux images de produits à l’aide d’une vidéo de référence soigneusement choisie montrant le mouvement d’un vêtement.

FAQ

Quelle est la différence entre Motion Control et Image-to-Video sur Novita AI ?

Image-to-Video (I2V) anime une image à partir d’un prompt textuel — le mouvement est généré par le modèle à partir de votre description. Motion Control transfère un mouvement spécifique d’une vidéo de référence vers le personnage de votre image. Motion Control offre un mouvement précis et reproductible ; I2V offre une flexibilité créative sans avoir besoin d’un clip de référence.

Le personnage de la vidéo de référence doit-il correspondre à l’apparence du personnage de l’image ?

Non. La vidéo de référence n’est utilisée que pour l’extraction du mouvement — le personnage final provient de l’image, pas de la vidéo. C’est la capacité essentielle : le mouvement d’une source, l’apparence d’une autre. Les proportions doivent à peu près correspondre (image en pied pour vidéo en pied, portrait pour vidéo en buste) pour une meilleure qualité de transfert.

Puis-je utiliser n’importe quelle vidéo accessible publiquement comme référence ?

Vous pouvez utiliser toute vidéo qui respecte les exigences de format et de taille. Le mouvement se transfère mieux à partir d’images où le sujet est clairement visible avec un minimum d’occlusion. Les scènes complexes à plusieurs personnes ou les séquences fortement éditées (coupures, zooms) peuvent réduire la précision.

Combien de temps prend la génération ?

En général, de 30 à 120 secondes selon la durée de sortie et le mode Standard ou Pro choisi. Interrogez toutes les 8 à 10 secondes plutôt que dans une boucle serrée.

Articles recommandés

• Kling 3.0 Now on Novita AI: Cinematic AI Video Generation at Scale
• Kling V3.0 4K API Quick Start
• Kling V2.5 Turbo API on Novita AI