Instructions d'intégration de l'API Kling Videos Generation

Ce document présente une méthode d’intégration de l’API Kling Videos Generation, qui permet de générer des vidéos officielles Kling en saisissant des paramètres personnalisés.

Processus de demande

Pour utiliser l’API, vous devez d’abord demander le service correspondant sur la page Kling Videos Generation API. Une fois sur la page, cliquez sur le bouton « Acquire », comme illustré ci-dessous :

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après connexion, vous reviendrez automatiquement à cette page. Lors de la première demande, un quota gratuit est offert, vous permettant d’utiliser l’API gratuitement.

Utilisation de base

Commençons par comprendre la méthode d’utilisation de base : en saisissant un mot-clé prompt, une action action, une image de référence pour la première image start_image_url ainsi qu’un modèle model, vous obtiendrez le résultat traité. Il faut d’abord transmettre un champ action dont la valeur est text2video. Cette action comprend principalement trois comportements : génération de vidéo à partir de texte (text2video), génération de vidéo à partir d’image (image2video), et extension de vidéo (extend). Ensuite, nous devons indiquer le modèle model. Actuellement, les modèles principaux sont kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1. Le détail est présenté ci-dessous :

Ici, nous configurons les en-têtes de la requête (Request Headers), comprenant :

accept : format de réponse souhaité, ici application/json pour un format JSON.
authorization : clé d’API pour appeler l’API, sélectionnable après la demande.

Le corps de la requête (Request Body) inclut :

model : modèle de génération vidéo, parmi kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1.
mode : mode de génération vidéo, options possibles : mode standard std, mode rapide pro et mode natif 4K 4k. Le mode 4k est uniquement supporté par kling-v3 et kling-v3-omni, et est incompatible avec camera_control (contrôle de caméra).
action : comportement de la tâche de génération vidéo, comprenant text2video, image2video et extend.
start_image_url : lien de l’image de référence pour la première image, obligatoire pour l’action image2video.
end_image_url : optionnel pour image2video, spécifie l’image finale.
duration : durée de la vidéo en secondes. Les modèles kling-v3 et kling-v3-omni supportent une durée flexible de 3 à 15 secondes (entiers), les autres modèles supportent 5 ou 10 secondes.
generate_audio : optionnel, booléen indiquant si un audio synchronisé doit être généré. Supporté par kling-v3, kling-v3-omni et kling-v2-6 (mode pro uniquement). Par défaut false.
aspect_ratio : ratio largeur/hauteur de la vidéo, options : 16:9, 9:16, 1:1, par défaut 16:9.
cfg_scale : intensité de la corrélation, plage [0,1], plus élevé signifie plus fidèle au prompt.
camera_control : optionnel, paramètres de contrôle du mouvement de la caméra, supporte les presets type/simple ainsi que les configurations horizontal, vertical, pan, tilt, roll, zoom, etc.
negative_prompt : optionnel, mots-clés négatifs à éviter, maximum 200 caractères.
element_list : liste de références principales, applicable uniquement au modèle kling-video-o1. Pour son usage, consultez la documentation officielle.
video_list : vidéos de référence via URL, applicable uniquement au modèle kling-video-o1. Pour son usage, consultez la documentation officielle.
prompt : mot-clé.
callback_url : URL pour le rappel de résultat.

Après sélection, le code correspondant est généré sur la droite, comme illustré :

Cliquez sur le bouton « Try » pour tester. Le résultat obtenu est le suivant :

{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}

Les champs retournés sont :

success : état de la tâche de génération vidéo.
task_id : identifiant de la tâche.
video_id : identifiant de la vidéo générée.
video_url : URL de la vidéo générée.
duration : durée de la vidéo générée.
state : état de la tâche.

Vous obtenez ainsi les informations vidéo souhaitées, il suffit d’accéder à l’URL vidéo dans le champ data pour récupérer la vidéo Kling générée. Pour générer directement le code d’intégration, vous pouvez copier le code généré, par exemple le code CURL suivant :

curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Matrice des capacités des modèles

Le support des paramètres varie considérablement selon les modèles. Le tableau ci-dessous est extrait de la documentation officielle des modèles vidéo Kling. Avant d’appeler, vérifiez que la combinaison actuelle model / mode / duration supporte les fonctionnalités requises, sinon des erreurs telles que model/mode/duration(...) is not supported with image_tail seront retournées.

Modèle	Mode	`end_image_url` (première et dernière image)	`generate_audio` (audio)	`camera_control` (mouvement caméra)	Remarques
`kling-v1`	std / pro	✅ uniquement `duration=5`	❌	✅ uniquement `duration=5`	`extend` ne supporte pas `negative_prompt` et `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Multi-image vidéo, `extend` disponible sur tous les modes
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	Mode unique, uniquement `duration=5/10`
`kling-v2-1-master`	—	❌	❌	❌	Mode unique, uniquement `duration=5/10`
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	Seul modèle non v3 supportant l’audio
`kling-v3`	std / pro	✅	✅	✅	`duration` 3–15 secondes
`kling-v3`	4k	✅	✅	❌	Mode 4K incompatible avec mouvement caméra
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-video-o1`	std / pro	✅	❌	❌	Supporte uniquement `duration=5/10`

Points importants :

Le mode 4k est supporté uniquement par kling-v3 et kling-v3-omni ; il est incompatible avec camera_control.
end_image_url ne peut être utilisé qu’avec action=image2video conjointement avec start_image_url. Fournir uniquement end_image_url sans start_image_url sera refusé.
kling-v3 / kling-v3-omni acceptent une durée entière flexible de 3 à 15 secondes ; les autres modèles acceptent uniquement 5 ou 10 secondes.
generate_audio est par défaut false. Seuls kling-v3, kling-v3-omni et kling-v2-6 (mode pro) le supportent.

Fonctionnalité d’extension vidéo

Pour continuer à générer une vidéo Kling déjà créée, définissez le paramètre action sur extend et saisissez l’ID de la vidéo à prolonger. L’ID vidéo s’obtient via l’utilisation de base comme illustré ci-dessous :

Ici, l’ID vidéo est :

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Notez que le champ video_id correspond à l’ID de la vidéo générée. Si vous ne savez pas comment générer une vidéo, reportez-vous à la section d’utilisation de base ci-dessus.

Ensuite, vous devez fournir un nouveau prompt pour personnaliser la génération de la vidéo étendue, avec les paramètres suivants :

model : modèle de génération vidéo, principalement kling-v1, kling-v1-5 et kling-v1-6.
mode : mode de génération vidéo, options std, pro et 4k (ce dernier uniquement pour kling-v3 et kling-v3-omni, incompatible avec contrôle caméra).
duration : durée de la nouvelle vidéo, généralement 5 ou 10 secondes.
start_image_url : obligatoire pour image2video, image de référence pour la première image.
prompt : mot-clé.

Exemple de saisie :

Le code généré automatiquement est :

Code Python correspondant :

import requests

url = "https://api.xhuoapi.ai/v1/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

En exécutant, vous obtiendrez un résultat similaire à :

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Le contenu est conforme à celui présenté précédemment, ce qui confirme la fonctionnalité d’extension vidéo.

Rappel asynchrone (callback)

La génération via Kling Videos Generation API prend environ 1 à 2 minutes. Si l’API ne répond pas rapidement, la requête HTTP reste ouverte, consommant des ressources système supplémentaires. Pour cela, l’API supporte un rappel asynchrone. Le processus est : le client envoie la requête en spécifiant un champ callback_url. L’API répond immédiatement avec un task_id représentant l’ID de la tâche. Une fois la tâche terminée, le résultat de la vidéo générée est envoyé en POST JSON à l’URL callback_url spécifiée, incluant également le task_id pour associer la réponse à la requête. Examinons un exemple. Le webhook est un service pouvant recevoir des requêtes HTTP. Le développeur doit remplacer par l’URL de son propre serveur HTTP. Pour la démonstration, nous utilisons le site public https://webhook.site/, qui génère une URL webhook, comme illustré :

Copiez cette URL, par exemple https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Ensuite, définissez le champ callback_url sur cette URL, et remplissez les autres paramètres comme ci-dessous :

En lançant la requête, vous obtenez immédiatement :

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Après un court instant, vous pouvez observer sur https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 le résultat de la vidéo générée, comme illustré :

Contenu reçu :

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

On remarque la présence du champ task_id qui permet d’associer la réponse à la requête initiale.

Gestion des erreurs

Lors d’un appel API, en cas d’erreur, l’API retourne un code et un message d’erreur, par exemple :

400 token_mismatched : requête incorrecte, paramètres manquants ou invalides.
400 api_not_implemented : requête incorrecte, paramètres manquants ou invalides.
401 invalid_token : non autorisé, token d’autorisation invalide ou manquant.
429 too_many_requests : trop de requêtes, limite de fréquence dépassée.
500 api_error : erreur serveur interne.

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Ce document vous a permis de comprendre comment utiliser l’API Kling Videos Generation pour générer des vidéos à partir de mots-clés et d’images de référence. Nous espérons que ce guide facilitera votre intégration et utilisation de l’API. Pour toute question, n’hésitez pas à contacter notre équipe de support technique.

Documentation Index

​Processus de demande

​Utilisation de base

​Matrice des capacités des modèles

​Fonctionnalité d’extension vidéo

​Rappel asynchrone (callback)

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion