API Kling : guide d’intégration officielle et via agrégateurs (2026)

Une requête vidéo Kling ne se résume pas à un appel d’API universel. Le modèle de génération vidéo de Kuaishou est accessible depuis l’Open Platform officielle, mais aussi via des agrégateurs comme WaveSpeedAI, KIE et fal. Chacun impose ses propres identifiants, IDs de modèles, formats de requête et règles de facturation. En revanche, le principe reste le même : soumettre un job asynchrone, enregistrer son ID, attendre un état final, puis récupérer le rendu sans lancer de nouvelles tentatives aveugles.

Choisissez votre accès avant de choisir un SDK

Kling propose une Open Platform officielle, mais les recherches sur « Kling API » font aussi remonter des passerelles indépendantes. Le bon choix dépend de l’accès fournisseur, de la vitesse d’intégration et du contrôle de la facturation, pas uniquement du nom du modèle.

Pour le détail des prix selon la résolution, consultez le guide tarifaire Kling 3 API 2026 existant. Dans cet article, considérez le prix, les multiplicateurs audio, la concurrence et la facturation des tâches échouées comme des paramètres propres à chaque fournisseur.

Le parcours avec Kling officiel

Privilégiez l’Open Platform officielle si vos contraintes d’achat exigent une relation directe avec Kuaishou ou si vous avez besoin de la disponibilité first-party des modèles. La documentation actuelle distingue la configuration des identifiants, la création de tâches, les callbacks, les règles de concurrence et les codes d’erreur : suivez donc ce parcours au lieu d’adapter une charge utile d’agrégateur.

1. Créez ou récupérez l’identifiant officiel depuis le guide d’authentification, puis conservez le token côté serveur.
2. Soumettez la tâche vidéo asynchrone documentée, avec l’endpoint spécifique au modèle et les champs indiqués dans la référence officielle.
3. Ajoutez callback_url si vous souhaitez recevoir les changements de statut. Les états de callback documentés sont submitted, processing, succeed et failed ; en cas d’échec, enregistrez task_status_msg.
4. Appliquez localement l’allocation de concurrence actuelle de votre compte. Le guide officiel de concurrence décrit une surcharge via HTTP 429 et le code métier 1303, et non comme une charge que Kling mettra forcément elle-même en attente.
5. Utilisez la référence des codes d’erreur officielle pour différencier les mauvais identifiants, paramètres invalides, ressources épuisées, blocages de politique et erreurs serveur réessayables.

La page d’authentification officielle est rendue côté client dans la version accessible de la documentation. Ce guide ne reproduit donc pas d’extrait non vérifié de génération de token. Reprenez le format d’identifiant actuel sur cette page au lieu de supposer qu’un header WaveSpeed, KIE ou fal fonctionnera.

Vous pouvez tout de même normaliser le cycle de vie officiel sans deviner le format exact de sa charge utile :

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

Il s’agit d’un schéma de cycle de vie, pas d’un endpoint à copier-coller. Consultez la référence officielle liée pour le token, le chemin, les champs de requête et l’enveloppe de réponse exacts.

Dans quels cas passer par un agrégateur

Les agrégateurs sont souvent plus rapides pour un prototype qui nécessite un accès à l’usage, un compte unique pour plusieurs modèles ou un SDK fournisseur. En contrepartie, ils contrôlent la clé, le schéma, la queue, l’URL de sortie et parfois la rétention. Avant toute nouvelle tentative, identifiez la couche à l’origine de l’échec.

Le contrat API Kling à normaliser sans risque

En production, votre client devrait masquer les particularités des fournisseurs derrière une fonction interne unique. Quel que soit l’accès retenu, votre application doit suivre ces étapes :

1. Valider le prompt et les URLs média avant de dépenser des crédits.
2. Soumettre une tâche de génération vidéo avec un ID de modèle propre au fournisseur.
3. Persister immédiatement l’ID de tâche ou de prédiction retourné.
4. Recevoir un callback ou interroger un endpoint de résultat jusqu’à ce que le job atteigne un état final.
5. Enregistrer l’URL de sortie, le fournisseur, le modèle, les paramètres et les métadonnées de coût.
6. Arrêter les tentatives lorsque le fournisseur signale un échec, une annulation, un timeout ou une suppression.

Votre abstraction devrait renvoyer son propre objet normalisé, par exemple :

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

Les paramètres faciles à transposer

Les concepts se retrouvent d’un service à l’autre, pas les noms de champs. generate_audio, sound et generate_audio: true peuvent désigner un comportement proche selon les services. Traitez donc le schéma de chaque fournisseur comme un adaptateur distinct.

Les paramètres qui ne se transposent pas

Les IDs de modèles sont le premier piège. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video et kwaivgi/kling-v3.0-std/text-to-video désignent des routes API différentes, pas des valeurs interchangeables.

La même règle vaut pour les headers d’authentification, noms de callback, URLs de résultat, valeurs de statut des tâches et règles d’upload de fichiers. Un client qui fige un statut comme completed pour un fournisseur peut mal interpréter la réponse succeeded ou failed d’un autre.

Trois formats de requête concrets

Ces exemples spécifiques à chaque fournisseur montrent bien pourquoi il n’existe pas un endpoint Kling universel.

WaveSpeedAI : un ID de prédiction puis lecture du résultat

WaveSpeedAI documente Kling 3.0 Standard text-to-video sur cet endpoint :

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

La requête utilise un token Bearer. L’endpoint renvoie un ID de prédiction, puis le résultat est disponible ici :

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

Voici un flux cURL minimal :

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

La documentation du modèle WaveSpeedAI indique une plage de 3 à 15 secondes, les ratios 16:9, 9:16 et 1:1, ainsi qu’un cfg_scale par défaut de 0.5. Sa grille tarifaire Standard affiche $0.42 pour un clip de 5 secondes sans son et $0.63 avec son. Considérez ces chiffres comme un instantané tarifaire propre au fournisseur, non comme le prix universel de Kling.

En production, interrogez l’endpoint de résultat avec un backoff plutôt que dans une boucle serrée. Arrêtez-vous sur completed, failed, cancelled, timeout ou deleted, les états finaux documentés pour cet endpoint.

KIE : createTask, callback ou interrogation de tâche

KIE utilise un endpoint commun de création de tâches :

POST https://api.kie.ai/api/v1/jobs/createTask

L’identifiant du modèle Kling 3.0 est kling-3.0/video, avec une authentification par token Bearer. Une charge utile compacte en single-shot ressemble à ceci :

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE documente des vidéos de 3 à 15 secondes, des ratios de sortie 16:9, 9:16 et 1:1, ainsi qu’un maximum de cinq plans en mode multi-shot. Les entrées multi-shot peuvent définir 1 à 12 secondes chacune. Les éléments image utilisent 2 à 4 URLs JPG ou PNG, avec une limite documentée de 10 MB par image ; les éléments vidéo utilisent une URL MP4 ou MOV, jusqu’à 50 MB.

Le callback est facultatif, mais recommandé par KIE en production. Votre webhook doit vérifier la signature lorsqu’elle est disponible, répondre rapidement, puis déposer le résultat de la tâche dans une queue. Gardez l’interrogation de tâche comme mécanisme de récupération si un callback est manqué.

KIE documente des codes de réponse distincts pour les échecs courants : 401 pour une authentification invalide, 402 pour des crédits insuffisants, 422 pour les erreurs de validation et 429 pour les limites de débit. Journalisez le code et le message ensemble : un simple message « Kling a échoué » ne suffit pas à déterminer si une nouvelle tentative est sans risque.

fal : endpoint de modèle et client de queue

fal expose Kling 3.0 via des IDs d’endpoint spécifiques aux modèles. Pour Standard text-to-video, l’ID documenté est :

fal-ai/kling-video/v3/standard/text-to-video

L’API brute utilise un header Authorization: Key $FAL_KEY. Les exemples Python et JavaScript s’appuient sur le client fal compatible avec les files d’attente, généralement plus simple que d’écrire vous-même la boucle d’interrogation.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal documente une plage de 3 à 15 secondes, trois ratios text-to-video et une plage de cfg_scale de 0 à 1, avec une valeur par défaut de 0.5. Son schéma Standard précise que prompt et multi_prompt sont alternatifs : fournissez l’un ou l’autre, jamais les deux. La valeur par défaut documentée pour generate_audio est true ; définissez-la donc explicitement si votre budget ou votre pipeline de post-production suppose une sortie sans son.

fal documente également des IDs séparés pour image-to-video et motion-control. Ne déduisez pas ces IDs en remplaçant simplement text-to-video dans une chaîne sans consulter la référence de modèle actuelle.

Quotas, temps d’attente et protection des crédits

Il n’existe pas de quota Kling public unique applicable à la plateforme officielle, WaveSpeedAI, KIE et fal. Concurrence, limites de débit, soldes de crédits, facturation des tâches échouées et rétention des sorties dépendent de l’accès choisi. Stockez ces valeurs dans une configuration par fournisseur, et non dans des constantes appelées KLING_LIMIT.

Un utilisateur a mieux résumé le risque opérationnel qu’une recommandation générique sur les tentatives :

« Kling facture chaque génération avec une vraie latence de queue. Le premier élément à câbler, c’est un plafond de coût et de concurrence ; sinon, un agent qui réessaie après une mauvaise image peut brûler vos crédits discrètement pendant la nuit. » — @ukrroot on X

Garde-fous pour le budget et la concurrence

Mettez en place ces contrôles avant d’autoriser un agent ou un worker batch à appeler Kling :

1. Nombre maximal de jobs en cours : Définissez un plafond par fournisseur au lieu de lancer un job pour chaque prompt.
2. Budget par job : Estimez la durée, le niveau, l’audio et le nombre de sorties avant la soumission.
3. Budget de tentatives : Réessayez sélectivement les erreurs de transport ; ne réessayez pas les erreurs de validation, d’authentification ou de crédits insuffisants.
4. Registre de jobs : Enregistrez l’ID du job fournisseur avant toute requête de suivi afin qu’un redémarrage de worker ne soumette pas une génération en double.
5. Politique d’état final : Considérez les jobs échoués, annulés, expirés ou supprimés comme terminés, sauf si le fournisseur indique explicitement qu’ils peuvent être resoumis sans risque.
6. Alerte crédit : Stoppez la queue lorsque le solde ou la dépense projetée franchit un seuil.
7. Sécurité des clés et sorties : Gardez les clés côté serveur, effectuez immédiatement une rotation des clés exposées et copiez les vidéos finalisées dans un stockage durable.

Un test Standard silencieux de cinq secondes peut coûter peu face à un job Pro de 15 secondes ou avec audio, mais cette notion reste propre à chaque fournisseur. Consultez la page de modèle en direct avant de fixer un niveau par défaut.

Les métriques à suivre avant la mise en production

Suivez ces champs pour chaque requête :

Considérez la latence et les quotas comme spécifiques à chaque endpoint : les sources publiques ne fournissent pas un SLA unique couvrant tous les fournisseurs.

FAQ sur l’API Kling

Kling propose-t-il une API officielle ?

Oui. Kling maintient un espace de documentation développeur pour son Open Platform officielle. Le parcours officiel et les passerelles tierces sont des services distincts : vérifiez donc les identifiants, quotas et tarifs actuels dans la documentation Kling Open Platform.

Existe-t-il un endpoint API Kling universel ?

Non. La plateforme officielle, WaveSpeedAI, KIE et fal utilisent des chemins d’endpoint, IDs de modèles, headers d’authentification et enveloppes de réponse différents. Créez un adaptateur par fournisseur au lieu de supposer que kling-3.0 est valable partout.

Faut-il utiliser le polling ou les webhooks ?

Utilisez un callback ou webhook en production lorsque le fournisseur le permet, mais conservez le polling pour les tests locaux et la récupération des callbacks manqués. Ajoutez un backoff exponentiel, une limite d’attente totale et de l’idempotence afin qu’un callback tardif ne crée pas de doublon.

Quelles durées et quels ratios sont pris en charge ?

Plusieurs documentations d’agrégateurs Kling 3.0 actuelles indiquent des clips de 3 à 15 secondes, avec les ratios 16:9, 9:16 et 1:1. Les endpoints peuvent varier : validez ces valeurs sur la page du modèle sélectionné au lieu de les traiter comme un contrat universel first-party.

Activer l’audio modifie-t-il le coût ?

Oui, cela peut généralement le modifier. WaveSpeedAI documente un multiplicateur sonore de 1.5× pour son endpoint Kling 3.0 Standard, tandis que fal et KIE exposent l’audio ou le son comme paramètres de requête. Consultez la page de facturation en direct de l’endpoint retenu et définissez explicitement le flag.

Pourquoi une nouvelle tentative a-t-elle créé des frais supplémentaires ?

Une nouvelle tentative peut déclencher une seconde génération alors que le premier job est encore en queue. Persistez l’ID du job, imposez un plafond de concurrence, ne réessayez que les erreurs transitoires et rapprochez la facturation fournisseur avant de resoumettre une requête ambiguë.

Pour votre premier test proche de la production, lancez un unique job Standard silencieux de 5 secondes, journalisez tout son cycle de vie, puis ajoutez Pro, l’audio, le multi-shot ou la concurrence seulement une fois la gestion des workers dupliqués fiable.