Guide d’intégration de l’API Kling Videos Generation

Cet article présentera un guide 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 Kling Videos Generation, rendez-vous d’abord sur la console Ace Data Cloud pour obtenir votre API Token, à conserver pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, puis vous reviendrez automatiquement sur la page actuelle une fois terminé. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir à effectuer une demande séparée pour chaque service. La première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde universel dans la console.

📘 Documentation complète : Kling Videos Generation API →

Utilisation de base

Commençons d’abord par comprendre le mode d’utilisation de base : il suffit de saisir le prompt prompt, l’action de génération action, l’image de référence de la première image start_image_url ainsi que le modèle model pour obtenir le résultat traité. Il faut d’abord transmettre simplement un champ action, dont la valeur est text2video. Il contient principalement trois actions : texte vers vidéo (text2video), image vers vidéo (image2video), extension de vidéo (extend). Ensuite, nous devons également saisir le modèle model. Les principaux modèles actuellement disponibles 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-o1, le contenu détaillé est le suivant :

On peut voir qu’ici nous avons configuré les Request Headers, y compris :

accept : le format de résultat de réponse que vous souhaitez recevoir ; saisissez ici application/json, c’est-à-dire le format JSON.
authorization : la clé pour appeler l’API, qui peut être directement sélectionnée dans la liste déroulante après la demande.

Les Request Body sont également configurés, y compris :

model : le modèle pour générer la vidéo, principalement les modèles 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-o1.
mode : le mode de génération de vidéo, les valeurs facultatives sont le mode standard std, le mode ultra-rapide pro et le mode natif 4K 4k. Parmi eux, 4k ne prend en charge que kling-v3 et kling-v3-omni, et n’est pas compatible avec camera_control (contrôle de mouvement de caméra).
action : l’action de cette tâche de génération de vidéo, contenant principalement trois actions : texte vers vidéo (text2video), image vers vidéo (image2video), extension de vidéo (extend).
start_image_url : le lien de l’image de référence de la première image qui doit être téléversée lorsqu’on choisit l’action image vers vidéo image2video.
end_image_url : facultatif pour l’image vers vidéo, spécifie la dernière image.
duration : la durée de la vidéo, en secondes. kling-v3 et kling-v3-omni prennent en charge une durée entière de 3 à 15 secondes ; kling-o1 ne prend en charge que 5 secondes ; les autres modèles prennent en charge 5 ou 10 secondes.
generate_audio : indique si l’audio doit être généré simultanément, facultatif, valeur booléenne. Pris en charge par kling-v3, kling-v3-omni et kling-v2-6 (mode pro uniquement). La valeur par défaut est false.
aspect_ratio : le ratio largeur-hauteur de la vidéo, facultatif, prend en charge 16:9, 9:16, 1:1, avec 16:9 par défaut.
cfg_scale : l’intensité de pertinence, plage [0,1], plus elle est élevée, plus le résultat correspond au prompt.
camera_control : facultatif, paramètres d’objet contrôlant le mouvement de la caméra, prenant en charge les préréglages type/simple ainsi que des configurations telles que horizontal, vertical, pan, tilt, roll, zoom.
negative_prompt : facultatif, le prompt négatif dont vous ne souhaitez pas l’apparition, jusqu’à 200 caractères.
image_list : liste d’images de référence Omni, applicable aux modèles kling-o1 et kling-v3-omni, voir ci-dessous « Référence Omni polyvalente » pour l’utilisation.
video_list : liste de vidéos de référence Omni (prend en charge le montage vidéo), applicable aux modèles kling-o1 et kling-v3-omni, voir ci-dessous « Référence Omni polyvalente » pour l’utilisation.
prompt : le prompt.
callback_url : l’URL nécessitant le résultat de rappel.
async : facultatif, lorsque défini sur true, l’interface renvoie immédiatement task_id, sans avoir besoin de fournir callback_url, puis récupère le résultat en interrogeant périodiquement l’interface de requête de tâche correspondante.

Après la sélection, vous pouvez constater que le code correspondant est également généré à droite, comme illustré ci-dessous :

Cliquez sur le bouton « Try » pour effectuer un test. Comme illustré ci-dessus, nous obtenons ici le résultat suivant :

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

Le résultat renvoyé comporte plusieurs champs, présentés comme suit :

success, l’état de la tâche de génération de vidéo à ce moment.
task_id, l’ID de la tâche de génération de vidéo à ce moment.
video_id, l’ID vidéo de la tâche de génération de vidéo à ce moment.
video_url, le lien vidéo de la tâche de génération de vidéo à ce moment.
duration, la durée du lien vidéo de la tâche de génération de vidéo à ce moment.
state, l’état de la tâche de génération de vidéo à ce moment.

On peut constater que nous avons obtenu des informations vidéo satisfaisantes ; il nous suffit de récupérer la vidéo Kling générée à partir de l’adresse du lien vidéo dans data du résultat. De plus, si vous souhaitez générer le code d’intégration correspondant, vous pouvez le copier directement. Par exemple, le code CURL est le suivant :

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "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

Les différents modèles présentent de grandes différences dans leur prise en charge des paramètres. La matrice suivante est compilée à partir de la documentation officielle Kling video models. Avant l’appel, veuillez d’abord vérifier si la combinaison actuelle model / mode / duration prend en charge les fonctionnalités dont vous avez besoin, sinon des erreurs telles que model/mode/duration(...) is not supported with image_tail seront renvoyées.

Modèle	Mode	`end_image_url`（première et dernière image）	`generate_audio`（audio d’accompagnement）	`camera_control`（mouvement de caméra）	Remarques
`kling-v1`	std / pro	✅ uniquement `duration=5`	❌	✅ uniquement `duration=5`	`extend` ne prend pas en charge `negative_prompt` ni `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Vidéo à partir de plusieurs images, tous les modes `extend` disponibles
`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	✅	✅	❌	Le seul modèle non-v3 prenant également en charge l’audio d’accompagnement
`kling-v3`	std / pro	✅	✅	✅	Plage de `duration` de 3 à 15 secondes
`kling-v3`	4k	✅	✅	❌	Le mode 4K est incompatible avec le mouvement de caméra
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-o1`	std / pro	✅	❌	❌	Prend uniquement en charge `duration=5`

Remarques :

mode=4k est uniquement pris en charge par kling-v3 et kling-v3-omni ; et il est mutuellement exclusif avec camera_control (mouvement de caméra).
end_image_url ne peut être utilisé avec start_image_url que lorsque action=image2video. Transmettre uniquement end_image_url (sans start_image_url) sera refusé.
kling-v3 / kling-v3-omni acceptent toute duration entière de 3 à 15 secondes ; kling-o1 accepte uniquement 5 ; les autres modèles acceptent uniquement 5 ou 10.
generate_audio est false par défaut. Seuls kling-v3, kling-v3-omni et kling-v2-6 (mode pro) sont pris en charge.

Fonction d’extension vidéo

Si vous souhaitez poursuivre la génération d’une vidéo Kling déjà générée, vous pouvez définir le paramètre action sur extend, et saisir l’ID de la vidéo à poursuivre. L’obtention de l’ID de la vidéo se fait selon l’utilisation de base, comme indiqué dans l’image ci-dessous :

À ce moment-là, vous pouvez voir que l’ID de la vidéo est :

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

Remarque : ici, le video_id dans la vidéo est l’ID de la vidéo après génération. Si vous ne savez pas comment générer une vidéo, vous pouvez vous référer à l’utilisation de base ci-dessus pour générer une vidéo.

Ensuite, nous devons remplir le prompt à étendre à l’étape suivante pour personnaliser la génération vidéo, et pouvons spécifier le contenu suivant :

model : le modèle pour générer la vidéo, principalement les modèles kling-v1, kling-v1-5 et kling-v1-6.
mode : le mode de génération vidéo, les valeurs facultatives sont le mode standard std, le mode rapide pro et le mode 4K natif 4k (uniquement pris en charge par kling-v3 et kling-v3-omni, incompatible avec le contrôle des mouvements de caméra).
duration : la durée vidéo de cette tâche de génération vidéo, comprenant principalement 5 s et 10 s.
start_image_url : lors du choix de l’action vidéo à partir d’image image2video, le lien de l’image de référence de première image à téléverser est obligatoire.
prompt : le prompt.

L’exemple de remplissage est le suivant :

Une fois le remplissage terminé, le code suivant est généré automatiquement :

Le code Python correspondant :

import requests

url = "https://api.acedata.cloud/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)

Cliquez sur exécuter, vous pouvez constater qu’un résultat sera obtenu, comme suit :

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

On peut voir que le contenu du résultat est cohérent avec celui ci-dessus, ce qui permet ainsi d’implémenter la fonction d’extension vidéo.

Référence Omni tout-en-un (édition vidéo / vidéo de référence / référence multi-images)

kling-o1 et kling-v3-omni sont deux modèles indépendants, et tous deux prennent en charge la capacité de « référence tout-en-un ». Sur la base de la génération vidéo à partir de texte (action=text2video), il est possible de transmettre en plus des images de référence ou des vidéos de référence, afin de réaliser la référence multi-images, la vidéo de référence ainsi que l’édition directe de vidéos existantes. Convention fondamentale : les éléments de référence doivent être cités dans le prompt sous la forme <<<image_1>>>, <<<video_1>>> (la numérotation commence à 1) afin de référencer les éléments à la position correspondante dans image_list / video_list, pour que le modèle applique ces références. Si seuls les éléments sont transmis sans être cités dans le prompt, les éléments seront ignorés.

Instructions de sécurité : l’API actuelle n’ouvre pas element_list. Les ID de la Kling Element Library ne sont pas isolés par locataire ; avant de fournir une API Element Management avec isolation par locataire, veuillez utiliser image_list pour transmettre les images de référence du sujet.

Les requêtes Omni ne prennent pas en charge negative_prompt, cfg_scale ou camera_control, et ne peuvent pas non plus utiliser mode=4k. Lorsqu’une vidéo de référence est incluse, generate_audio doit être false. video_list est utilisé pour transmettre des vidéos de référence ; il s’agit du scénario le plus courant de cette capacité. Les champs des éléments du tableau sont les suivants :

video_url : lien de la vidéo de référence, ne peut pas être vide. Au maximum 1 vidéo MP4/MOV, taille du fichier ≤200MB, fréquence d’images 24–60fps. kling-o1 exige une durée de 3–10 secondes et une largeur et une hauteur de 700–2160px chacune ; kling-v3-omni exige une durée de 3–15.5 secondes, une largeur et une hauteur de 700–4553px chacune, un total de pixels ≤8,294,400, et un rapport largeur/hauteur de 0.4–2.
refer_type : type de référence, peut être base (par défaut, vidéo de base à éditer, c’est-à-dire « éditer directement la vidéo », avec possibilité d’ajouter/supprimer/modifier des éléments, changer la composition, le style, les couleurs, la météo, etc.) ou feature (référence de caractéristiques, en référence à son style / ses mouvements de caméra / la poursuite de la prise suivante).
keep_original_sound : conserver ou non l’audio original de la vidéo, peut être yes (conserver) ou no (supprimer).

Remarque : lorsqu’une vidéo de référence est présente, generate_audio doit être false. Une vidéo avec refer_type=base ne peut plus spécifier une image de début / de fin.

Voici un exemple CURL pour éditer une vidéo existante (transformer la vidéo en style animé) :

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

Référence multi-images (`image_list`)

image_list est utilisé pour transmettre des images de référence (éléments / scènes / styles, etc.). Les champs des éléments du tableau sont les suivants :

image_url : lien de l’image de référence, ne peut pas être vide. Exigences : format .jpg/.jpeg/.png ; taille du fichier ≤10MB ; côté le plus court ≥300px ; rapport largeur/hauteur de 1:2.5 ~ 2.5:1.
type : facultatif. Lorsqu’il n’est pas transmis, il est utilisé comme image de référence pure ; lorsque first_frame / end_frame est transmis, il est respectivement utilisé comme image de début / de fin (équivalent à start_image_url / end_image_url).

Lors de l’utilisation, il faut les référencer dans le prompt avec <<<image_1>>>, <<<image_2>>>. Limite de quantité : en l’absence de vidéo de référence, images de référence ≤ 7 ; en présence d’une vidéo de référence, images de référence ≤ 4. Lors de la transmission uniquement d’une image de début / de fin, start_image_url / end_image_url peut également être utilisé directement, mais l’image de fin doit être utilisée avec l’image de début.

Remarque : si start_image_url / end_image_url et image_list sont transmis simultanément, les images de début / de fin seront placées avant image_list, ce qui peut affecter la correspondance des numéros de <<<image_N>>>. Il est recommandé de choisir l’un des deux : lorsqu’une image de début / de fin est nécessaire, spécifiez directement le type dans image_list, sans le mélanger avec start_image_url / end_image_url.

Exemple CURL de génération vidéo avec référence multi-images :

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

Rappel asynchrone

Étant donné que le temps de génération de Kling Videos Generation API est relativement long, environ 1 à 2 minutes, si l’API ne répond pas pendant une longue période, la requête HTTP maintiendra continuellement la connexion, entraînant une consommation supplémentaire de ressources système ; cette API prend donc également en charge les rappels asynchrones. Le processus global est le suivant : lorsque le client lance une requête, il spécifie en plus un champ callback_url. Après que le client a lancé la requête API, l’API renvoie immédiatement un résultat contenant un champ task_id, qui représente l’ID de la tâche actuelle. Une fois la tâche terminée, le résultat de la vidéo générée sera envoyé sous forme de POST JSON à l’callback_url spécifié par le client, contenant également le champ task_id, afin que les résultats de la tâche puissent être associés via l’ID. Examinons ci-dessous la procédure spécifique à travers un exemple. Tout d’abord, le rappel Webhook est un service capable de recevoir des requêtes HTTP ; le développeur doit le remplacer par l’URL de son propre serveur HTTP. Afin de faciliter la démonstration, un site d’exemple Webhook public, https://webhook.site/, est utilisé ici. Ouvrez ce site pour obtenir une URL Webhook, comme illustré ci-dessous :

Copiez cette URL afin de l’utiliser comme Webhook ; l’exemple ici est https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Ensuite, nous pouvons définir le champ callback_url sur l’URL Webhook ci-dessus, tout en renseignant les paramètres correspondants ; le contenu spécifique est illustré ci-dessous :

Cliquez sur exécuter, et vous constaterez qu’un résultat est obtenu immédiatement, comme suit :

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

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

Le contenu est le suivant :

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

On peut voir qu’il y a un champ task_id dans le résultat ; les autres champs sont similaires à ceux ci-dessus, et ce champ permet d’associer les tâches.

Gestion des erreurs

Lors de l’appel de l’API, si une erreur survient, l’API renverra le code et les informations d’erreur correspondants. Par exemple :

400 token_mismatched : Mauvaise requête, probablement en raison de paramètres manquants ou non valides.
400 api_not_implemented : Mauvaise requête, probablement en raison de paramètres manquants ou non valides.
401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
429 too_many_requests : Trop de requêtes, vous avez dépassé la limite de débit.
500 api_error : Erreur interne du serveur, un problème est survenu sur le serveur.

Exemple de réponse d’erreur

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

Conclusion

À travers ce document, vous avez appris comment utiliser l’API Kling Videos Generation pour générer des vidéos en saisissant des invites ainsi que des images de référence de première image. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, veuillez contacter notre équipe de support technique à tout moment.

Kling 3.0 Turbo

model="kling-v3-turbo" prend en charge la génération de vidéos à partir de texte et à partir d’une image de première image, avec une durée entière de 3 à 15 secondes. mode="std" produit du 720p, mode="pro" produit du 1080p. Ce modèle intègre un audio natif et ne propose pas d’interrupteur pour le désactiver ; omettez generate_audio ou définissez-le sur true. Ce modèle ne prend pas en charge l’image finale, les objets de mouvement de caméra, les invites négatives indépendantes ou cfg_scale. Veuillez décrire directement dans prompt le contenu souhaité ou à éviter.

Vidéos à plans multiples

kling-v3 et kling-v3-omni prennent en charge multi_shot=true. shot_type="intelligence" génère automatiquement le découpage des plans selon prompt ; shot_type="customize" fournit 1 à 6 plans via multi_prompt, chaque élément contenant un index incrémenté continuellement à partir de 1, un prompt de 512 caractères maximum et une duration entière d’au moins 1 seconde. La somme des durées de tous les plans doit être égale à la duration totale. Les plans personnalisés n’utilisent pas le prompt global. Les vidéos à plans multiples sont facturées selon le modèle sélectionné, la qualité d’image, la configuration audio et la durée totale.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Guide d’intégration de l’API Kling Videos Generation

Processus de demande

Utilisation de base

Matrice des capacités des modèles

Fonction d’extension vidéo

Référence Omni tout-en-un (édition vidéo / vidéo de référence / référence multi-images)

Référence multi-images (`image_list`)

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

Kling 3.0 Turbo

Vidéos à plans multiples

​Processus de demande

​Utilisation de base

​Matrice des capacités des modèles

​Fonction d’extension vidéo

​Référence Omni tout-en-un (édition vidéo / vidéo de référence / référence multi-images)

​Vidéo de référence et édition vidéo (video_list)

​Référence multi-images (image_list)

​Rappel asynchrone

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

​Kling 3.0 Turbo

​Vidéos à plans multiples

Processus de demande

Utilisation de base

Matrice des capacités des modèles

Fonction d’extension vidéo

Référence Omni tout-en-un (édition vidéo / vidéo de référence / référence multi-images)

Vidéo de référence et édition vidéo (`video_list`)

Référence multi-images (`image_list`)

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

Kling 3.0 Turbo

Vidéos à plans multiples