L'interface de génération vidéo Kling fonctionne par tâches asynchrones. La première étape n'est pas d'écrire une requête, mais d'obtenir un identifiant, de le placer au bon endroit et d'en maîtriser les droits. Beaucoup de 401 et 403 ne viennent pas du code : la clé a été mal copiée, la variable d'environnement n'est pas chargée, ou le compte n'a tout simplement pas accès au modèle concerné.

Cet article suit l'ordre « créer — configurer — diagnostiquer — renouveler » et décrit les formes d'identifiants courantes sur la plateforme ouverte Kling en 2026, ainsi que les bonnes pratiques de sécurité. Les détails d'interface évoluent vite : la console et la documentation officielles font foi.

Remarque : Kling et Kuaishou sont des marques de leurs détenteurs respectifs. Cet article est purement technique et n'implique aucune affiliation ni relation d'agence avec les sociétés concernées.

1. Identifier le type d'identifiant nécessaire

Deux formes d'authentification coexistent généralement :

  • Clé API : créée dans la console développeur, placée dans Authorization: Bearer <API_KEY>. L'interface récente distingue les modèles par le chemin ; c'est l'option à privilégier.
  • AccessKey + SecretKey : surtout utilisée par l'ancienne interface. Chaque requête signe un JWT avec le SecretKey, puis place le JWT dans l'en-tête Bearer. L'AccessKey figure dans la revendication iss.

Les exigences de sécurité diffèrent : une clé API est un identifiant longue durée qui permet un appel direct en cas de fuite ; dans AccessKey/SecretKey, le SecretKey est la clé de signature, et un attaquant peut émettre ses propres jetons s'il le découvre. Dans les deux cas, jamais de clé dans un frontend, un paquet mobile ou un dépôt public.

2. Créer une clé API Kling

La console du site international est accessible à l'adresse https://kling.ai/dev/api-key ; connectez-vous avec votre compte Kling pour gérer les clés. L'entrée nationale et les modèles disponibles sont à vérifier sur la page officielle : ne recopiez pas un domaine reconstitué à partir d'un tutoriel tiers.

  1. Connectez-vous à la console développeur et ouvrez la gestion des clés API.
  2. Cliquez sur « + Create a new API Key » et nommez selon « projet — environnement — usage », par exemple video-prod-cn ou video-test.
  3. Copiez et conservez la clé immédiatement. La page ne l'affiche généralement qu'une fois ; après fermeture, la valeur complète n'est plus visible.
  4. Enregistrez la clé dans un gestionnaire de mots de passe ou un service de secrets cloud, avec le créateur, l'usage et la date de rotation.
  5. Validez l'authentification avec une tâche au coût minimal et notez le request_id renvoyé pour faciliter le diagnostic.
  6. Confirmez que le compte dispose d'un pack utilisable ou d'un post-paiement activé avant l'intégration réelle.

Le nommage n'est pas décoratif. En cas d'appel anormal, il permet d'identifier immédiatement le service et l'environnement concernés, sans arrêter toute l'activité.

3. Ancienne authentification AccessKey/SecretKey et JWT

L'ancienne interface précise le modèle via model_name dans le corps et exige de générer un JWT. La documentation officielle indique une signature HS256, iss contenant l'AccessKey, exp à l'heure courante plus 1800 secondes, et nbf à l'heure courante moins 5 secondes.

import os
import time
import jwt  # PyJWT

access_key = os.environ["KLING_ACCESS_KEY"]
secret_key = os.environ["KLING_SECRET_KEY"]

token = jwt.encode(
    {
        "iss": access_key,
        "exp": int(time.time()) + 1800,
        "nbf": int(time.time()) - 5,
    },
    secret_key,
    algorithm="HS256",
    headers={"alg": "HS256", "typ": "JWT"},
)
print(token)

Quelques pièges fréquents :

  • exp est en secondes Unix, pas en millisecondes ; une valeur en millisecondes produit un jeton qui n'expire que très tard, mais que la plateforme peut refuser.
  • L'horloge serveur doit être synchronisée. Un décalage important fait échouer la vérification nbf, avec un message du type « token pas encore valide ».
  • Un JWT n'est valable que 30 minutes ; pendant l'interrogation d'une tâche longue, il faut le régénérer, pas le réutiliser jusqu'au bout.
  • Ne mélangez pas JWT et clé API. L'interface récente utilise la clé API, l'ancienne passe par la signature AK/SK ; référez-vous à la documentation de l'interface concernée.

4. Droits, packs et limites de concurrence

L'erreur de droits principale de la documentation Kling est le code métier 1103 (HTTP 403), qui signifie « pas de droit sur cette API ou ce modèle ». Elle relève généralement de l'état du compte, de l'activation du modèle ou du pack, pas d'une clé invalide.

Trois catégories de limites sont à distinguer :

  • État du compte : 1100 signale un compte anormal ; 1101 un impayé en post-paiement ; 1102 un pack prépayé épuisé ou expiré.
  • Droits sur le modèle : 1103 indique que le compte n'a pas le droit d'appeler cette interface ou ce modèle.
  • Quota de concurrence : les tâches vidéo disposent de slots liés au pack ; au-delà, la réponse est 1303. La documentation précise que toutes les clés API d'un même compte partagent le même pool de concurrence.

Cela signifie que multiplier les clés n'augmente pas la concurrence et ne sépare pas réellement production et test. Pour une isolation stricte, utilisez des comptes ou des packs distincts et prévoyez une file de tâches dans l'architecture. La documentation Kling ne décrit pas, à ce jour, de scopes fins de type lecture seule ou génération par interface : les droits sont liés au compte et aux capacités achetées. Si la console ajoute une autorisation fine, elle fera foi.

5. Placer la clé dans des variables d'environnement et un coffre

Le minimum est la variable d'environnement ; en production, utilisez un Secrets Manager cloud, un Secret Kubernetes ou un service équivalent. Ne committez pas la clé dans Git et n'imprimez jamais sa valeur complète dans les journaux.

Nommage recommandé :

KLING_API_KEY=...
KLING_ACCESS_KEY=...
KLING_SECRET_KEY=...
KLING_BASE_URL=https://api-singapore.klingai.com

Ne conservez dans le dépôt qu'un .env.example avec des valeurs fictives. Au démarrage, l'application doit vérifier la présence des variables et échouer franchement si elles manquent, plutôt que d'envoyer une chaîne vide. Dans les journaux, limitez-vous aux 4 premiers et 4 derniers caractères de la clé, avec le request_id. Ni le navigateur ni l'application mobile ne doivent détenir la clé : toutes les tâches vidéo passent par un proxy backend.

6. Tableau de diagnostic des 401

Code métier HTTP Signification Cause fréquente Traitement
1000 401 Échec d'authentification Format d'en-tête incorrect Vérifier la présence de Authorization
1001 401 En-tête d'authentification vide Variable vide, en-tête supprimé par un proxy Afficher la longueur de la variable, vérifier le transfert
1002 401 Identifiant invalide Clé incomplète, révoquée, mauvais environnement Recréer et mettre à jour la clé
1003 401 Jeton pas encore valide Décalage d'horloge, nbf mal réglé Synchroniser NTP, vérifier l'unité de temps
1004 401 Jeton expiré Ancien JWT de plus de 30 minutes Régénérer le JWT

Procédez de l'extérieur vers l'intérieur : confirmez d'abord que l'en-tête est bien présent, puis que la clé correspond à l'environnement courant, et seulement ensuite soupçonnez la plateforme. Si vous passez par un proxy inverse ou une plateforme serverless, vérifiez qu'elle ne filtre pas l'en-tête Authorization.

7. Accès direct ou passerelle API

En accès direct à la plateforme Kling, le compte, les packs, les journaux d'appel et la facture restent chez vous ; c'est adapté aux équipes ayant une capacité d'achat et d'exploitation. Une passerelle API permet de regrouper plusieurs modèles vidéo sous une clé et une facture, ce qui réduit le coût d'intégration.

Pour choisir une passerelle, confirmez quatre points : le canal vidéo Kling est-il activé, les tâches asynchrones et external_task_id sont-ils transmis tels quels, l'URL de callback peut-elle être transmise, et comment les URL de résultat sont-elles livrées. Une passerelle limitée à une interface texte compatible OpenAI ne convient pas aux tâches vidéo. Consultez les modèles et tarifs, inscrivez-vous pour tester, validez avec une tâche minimale, puis décidez du transfert de la production.

8. Rotation et gestion d'une fuite

La rotation des clés doit être une opération routinière, pas une réaction à un incident. Prévoyez-la tous les 90 jours, et immédiatement au départ d'une personne ou lors d'un transfert de projet.

  1. Créez une nouvelle clé dans la console, avec la date dans le nom, par exemple video-prod-20261019.
  2. Enregistrez-la dans le service de secrets, mettez à jour l'environnement de test et validez une tâche minimale.
  3. Déployez progressivement en production et surveillez les 401, 403 et le taux de réussite.
  4. Une fois la nouvelle clé stable, révoquez l'ancienne.
  5. Consignez la date de rotation, l'opérateur et les services concernés.

En cas de fuite suspectée, révoquez d'abord l'ancienne clé, consultez ensuite les journaux d'appel et la facture, puis seulement recherchez le vecteur de fuite. Modifier le code sans révoquer l'identifiant laisse le risque intact. Le Webhook Secret est un identifiant distinct ; la documentation officielle permet la coexistence de l'ancien et du nouveau pendant 7 jours, et sa rotation peut être séparée de celle de la clé API.

Questions fréquentes

Quelle différence entre une clé API Kling et AccessKey/SecretKey ?

La clé API est un identifiant unique placé directement dans l'en-tête Bearer ; AccessKey/SecretKey est l'ancien mécanisme de signature, qui exige de générer un JWT. L'interface récente privilégie la clé API, l'ancienne suit la documentation JWT.

Peut-on créer plusieurs clés API sur un compte ? La concurrence s'additionne-t-elle ?

Oui, par environnement et par projet, mais la documentation précise que toutes les clés d'un compte partagent le pool de concurrence : en créer davantage n'augmente pas la concurrence. Pour une isolation stricte, utilisez des comptes ou des packs distincts.

Le message 401 dit « identifiant invalide » alors que la clé semble correcte. Que faire ?

Vérifiez que la chaîne complète a été copiée, sans espace ni retour à la ligne, que la requête vise la bonne région, et que le proxy ne réécrit ni ne supprime l'en-tête Authorization. Si le problème persiste, créez une clé de contrôle pour comparer.

Une clé API Kling expire-t-elle ?

La clé elle-même n'expire généralement pas selon un calendrier fixe, mais elle peut devenir invalide après révocation, changement d'état du compte ou des droits. L'ancien JWT, lui, dure 30 minutes. La politique exacte figure dans la console et la documentation officielle.

Faut-il encore un compte Kling si l'on passe par une passerelle API ?

Pas nécessairement. Une passerelle héberge souvent le compte amont et la facturation, mais les modèles disponibles, la concurrence, les callbacks et la conservation des données dépendent d'elle. Vérifiez l'activation du canal vidéo et lisez ses conditions de service avant l'intégration.

Lectures associées :