API Kling 3.0 : migration, Motion Control et code

Passer de Kling 2.6 à Kling 3.0 ne se résume pas à remplacer un nom de modèle dans une requête. Kling 3.0 est officiellement disponible, mais les routes V3, Turbo, Omni et Motion Control n’offrent ni les mêmes capacités ni les mêmes schémas. La migration la plus sûre consiste à choisir d’abord la bonne route, puis à introduire progressivement l’audio, le multi-plan et les contrôles par référence.

Choisir la route avant d’écrire l’intégration

Selon le guide officiel de Kling consacré à VIDEO 3.0, cette génération prend la relève de VIDEO 2.6 et VIDEO O1 : VIDEO 2.6 évolue vers VIDEO 3.0, tandis que VIDEO O1 évolue vers VIDEO 3.0 Omni. L’API développeur sépare les opérations selon les modèles. Autrement dit, « API Kling 3.0 » désigne une famille d’accès, pas un corps de requête universel.

L’erreur d’intégration la plus fréquente consiste à confondre le schéma simplifié d’un fournisseur avec le schéma direct de Kling : la requête hébergée de Krea est un exemple fonctionnel, mais ne prouve pas que la même URL ou les mêmes champs s’appliquent à la documentation développeur officielle de Kling.

Pour une vue plus large des différentes routes, consultez le guide d’intégration de l’API Kling. Cet article se concentre sur la migration vers Kling 3.0 et le comportement des endpoints.

Les évolutions entre Kling 2.6 et 3.0

Le guide de modèles de Kling met surtout en avant les gains en matière de contrôle, de continuité et de direction audiovisuelle, plutôt qu’un simple nouveau préréglage de résolution. Le tableau ci-dessous reprend les capacités attribuées par Kling à cette famille de modèles.

Dans la pratique, une intégration 2.6 fondée sur un prompt court unique peut devenir, avec 3.0, une séquence véritablement dirigée. Le guide de Kling revendique aussi une meilleure conservation des personnages, objets et détails de décor lors des mouvements de caméra, sans publier de benchmark indépendant sur cette cohérence. Il faut donc distinguer cette promesse de ce que votre application est réellement en mesure de tester.

Mettre en place l’intégration asynchrone minimale avec Krea

La génération vidéo est asynchrone. Votre application doit soumettre une tâche, conserver son identifiant, interroger son état ou recevoir un callback, puis stocker le résultat final. Ne laissez pas la requête HTTP d’origine ouverte pendant le rendu du modèle.

L’exemple ci-dessous s’appuie sur l’endpoint Kling 3.0 documenté publiquement par Krea, car sa requête et ses champs de tâche sont visibles dans le guide API Kling 3.0 publié par le fournisseur. Ne remplacez l’URL et les noms de champs propres au fournisseur qu’après avoir vérifié le schéma officiel de Kling que vous comptez utiliser.

Soumettre une tâche de génération

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

La réponse documentée par Krea contient un job_id et un statut initial tel que scheduled. L’exemple du fournisseur utilise un endpoint distinct de consultation des tâches pour vérifier l’avancement. Votre base de données doit enregistrer cet identifiant avec votre propre identifiant de commande avant le début du polling.

Interroger l’état avec un délai maximal et enregistrer le résultat

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

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Les exemples de Krea ont pris 51 secondes et 2 minutes 3 secondes. Prévoyez donc des délais adaptés à la file d’attente plutôt que de promettre un temps de génération Kling fixe.

En production, un webhook peut éviter les interrogations répétées. Vérifiez que le job ID correspond bien à une tâche créée par votre système, rendez le handler idempotent et ne considérez pas un callback non signé comme une preuve d’identité à lui seul.

Ajouter les contrôles 3.0 progressivement

Les noms de paramètres diffèrent entre l’API Kling directe et les fournisseurs hébergés. Créez une petite couche de compatibilité au lieu de disséminer du JSON spécifique à chaque fournisseur dans toute l’application.

Le guide officiel prend en charge l’audio natif, les références d’éléments, les récits multi-plans et cinq langues de dialogue nommées. L’endpoint API choisi peut n’exposer qu’une partie de ces fonctions disponibles à l’échelle de la famille.

Un payload multi-plan personnalisé

Le schéma documenté de Krea utilise des segments multi_prompt minutés. C’est un modèle utile pour une intégration hébergée :

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Vérifiez que la durée au niveau supérieur correspond à la somme des durées de chaque segment. Krea indique un résultat de 12,04 secondes pour un test de trois segments totalisant 12 secondes : ne supposez donc pas que la durée du fichier sera exacte à la milliseconde près.

Chaque segment Krea est limité à 512 caractères, et la séquence dirigée complète est plafonnée à 15 secondes. Rédigez chaque segment comme une consigne de plan — sujet, évolution et caméra — plutôt que comme une longue description de scène. Si votre route Kling directe repose plutôt sur la grammaire officielle des plans, conservez le même modèle de timeline mais traduisez le payload à la frontière de l’adaptateur.

Contraintes audio et linguistiques

Le guide officiel cite le chinois, l’anglais, le japonais, le coréen et l’espagnol parmi les langues de dialogue prises en charge, et évoque dialectes, accents, dialogues propres aux personnages et scènes multilingues. Il indique que les dialogues non pris en charge sont traduits en anglais ; une application multilingue ne doit donc pas supposer que chaque langue source sera préservée telle quelle.

L’audio a également un impact sur le coût. Les tarifs publiés par Krea affichent std à $0.1764 par seconde sans audio et $0.2646 avec audio ; pro coûte $0.2352 sans audio et $0.3528 avec audio. Le tarif 4K indiqué est de $0.441 par seconde, avec ou sans audio. Il s’agit de tarifs Krea, et non d’une grille tarifaire universelle pour l’API Kling.

Un cycle d’itération raisonnable consiste à produire d’abord des brouillons muets, puis à activer l’audio sur le candidat final en std ou pro.

En production : coût, vitesse et gestion des échecs

Le guide grand public officiel de Kling indique que VIDEO 3.0 coûte 6 crédits par seconde en 720p sans audio natif, 8 crédits par seconde en 1080p sans audio natif, 9 crédits par seconde en 720p avec audio et 12 crédits par seconde en 1080p avec audio. Voice Control ajoute 2 crédits par seconde. Ces chiffres éclairent les coûts relatifs dans ce guide ; ils ne doivent pas être convertis en prix API développeur en dollars sans consulter la page de tarification développeur en vigueur.

Le choix ne se limite pas à « quel modèle est le moins cher ? ». Il porte aussi sur la facturation et l’exploitation :

Traitez les échecs par catégorie :

1. Réessayez les erreurs transitoires du fournisseur avec un backoff exponentiel plafonné.
2. Ne réessayez pas des paramètres invalides avant que votre adaptateur ait corrigé le payload.
3. Conservez une clé d’idempotence côté client ou un identifiant de commande afin qu’un timeout réseau ne crée pas une tâche dupliquée passée inaperçue.
4. Imposez un plafond strict en dollars ou en crédits pour les générations par lot.
5. Téléchargez ou copiez le résultat vers un stockage durable avant l’expiration de l’URL temporaire du fournisseur.
6. Journalisez ensemble la variante de modèle, la durée, le réglage audio, le niveau de résolution et le fournisseur ; « Kling 3.0 » seul ne suffit pas pour suivre les coûts.

Checklist de migration de Kling 2.6 vers 3.0

1. Inventoriez les appels 2.6 existants. Relevez les IDs de modèle, les entrées image, les images de début et de fin, la durée, l’audio et le comportement des callbacks.
2. Choisissez la route de la famille 3.0. Utilisez V3 pour la génération cinématographique guidée par prompt, Turbo pour la route la plus rapide, Omni pour le parcours multimodal de type O1, et Motion Control pour les usages fondés sur une référence de mouvement.
3. Créez un adaptateur par fournisseur. Gardez les schémas de Kling direct, Krea et des autres offres hébergées derrière des traducteurs distincts.
4. Migrez d’abord la requête minimale. Testez une génération muette de cinq secondes en 16:9 avant d’ajouter l’audio ou les contrôles multi-plans.
5. Ajoutez un contrôle à la fois. Validez la durée, puis l’audio, la direction des plans et enfin les références. Il devient ainsi plus simple d’isoler un champ défaillant.
6. Testez les états terminaux. Couvrez les cas de réussite, échec, annulation, timeout, callback dupliqué et URL de sortie expirée.
7. Lancez un déploiement parallèle chiffré. Comparez un ensemble fixe de prompts entre 2.6 et 3.0 avec la même durée et le même niveau de sortie, puis déterminez si le gain en qualité ou en contrôle justifie la nouvelle route.

La migration est terminée lorsque votre application peut revenir à l’ancien identifiant de modèle sans modifier la logique métier, les contrôles de facturation ni le traitement des résultats.

FAQ sur l’API Kling 3.0

Existe-t-il une API officielle Kling 3.0 ?

Oui. La documentation développeur officielle de Kling expose des pages API propres aux modèles 3.0, et le guide first-party de Kling présente VIDEO 3.0 comme le successeur de VIDEO 2.6. Consultez le schéma exact dans la console développeur active, car certaines pages sont rendues côté client.

Motion Control est-il un paramètre de Kling 3.0 ?

Ne le présumez pas. Motion Control est une capacité spécialisée qui possède sa propre page modèle dans l’écosystème Kling. Utilisez l’opération et le schéma d’entrée documentés par le fournisseur choisi au lieu d’ajouter un champ motion_control non vérifié à une requête text-to-video standard.

Quelle durée peut générer Kling VIDEO 3.0 ?

Le guide officiel de modèles Kling indique que VIDEO 3.0 prend en charge des sorties flexibles de 3 à 15 secondes. Une route hébergée ou Turbo donnée peut imposer des limites plus étroites : validez donc l’endpoint retenu.

Kling 3.0 prend-il en charge l’audio natif ?

Oui, selon le guide officiel de VIDEO 3.0, qui décrit des dialogues spécifiques aux personnages, plusieurs langues, des dialectes et des accents. Le caractère facultatif de l’audio et son mode de facturation dépendent toutefois de l’endpoint ou du schéma du fournisseur.

Kling 3.0 Omni est-il identique à Kling 3.0 standard ?

Non. Kling positionne VIDEO 3.0 comme le successeur de 2.6, et VIDEO 3.0 Omni comme le successeur de O1. Les pages des fournisseurs peuvent les exposer avec des IDs de modèle distincts et différents contrôles de référence ou de voix.

Un abonnement web Kling peut-il financer des appels API ?

Considérez les abonnements grand public et la facturation de l’API développeur comme séparés tant que la documentation active du compte n’indique pas le contraire. La route API exige normalement son propre compte développeur, sa clé et sa configuration de facturation.

La bonne frontière de migration est simple : conservez le cycle de vie des tâches de l’intégration 2.6, remplacez l’adaptateur spécifique au modèle et vérifiez chaque nouveau contrôle 3.0 sur la route qui le sert réellement. Vous éviterez ainsi le type d’échec le plus coûteux : une intégration qui soumet correctement ses tâches tout en utilisant silencieusement la mauvaise variante, le mauvais mode audio ou le mauvais niveau de facturation.