> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling 3.0 Turbo Les paramètres et leur utilisation sont alignés sur la documentation officielle. Pour le détail des paramètres, veuillez vous référer directement à la documentation officielle. ## I. Aperçu Ce document explique comment utiliser les capacités de texte vers vidéo et d'image vers vidéo via le protocole natif de Kling 3.0 Turbo. Turbo utilise le même protocole natif que Kling 3.0 standard ; la structure des requêtes et des réponses est identique, seules diffèrent l'étendue des capacités, les paliers de résolution et la facturation. Les deux capacités utilisent un mode de tâche asynchrone : 1. Appelez l'interface de création correspondante. 2. Enregistrez le champ `data.id` de la réponse de création. 3. Utilisez la même clé API que celle utilisée pour créer la tâche afin d'interroger son statut. 4. Une fois la tâche réussie, récupérez et enregistrez la vidéo générée depuis `outputs`. ### 1.1 Adresses API | Capacité | Création de tâche | Interrogation de tâche | | - | - | - | | Texte vers vidéo | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | | Image vers vidéo | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | Dans les exemples de ce document, l'adresse complète correspond à `https://{api_domain}` suivi du chemin d'interface indiqué dans le tableau, où `{api_domain}` est le domaine API que vous utilisez. Turbo fournit uniquement la génération de vidéo à partir de texte et à partir d'image ; il ne prend pas en charge la vidéo Omni ni le contrôle de mouvement. ### 1.2 Authentification Toutes les requêtes doivent comporter une clé API. Les requêtes POST doivent en outre spécifier le type de contenu JSON : ``` Authorization: Bearer Content-Type: application/json ``` ### 1.3 Structure de la réponse Dans la réponse de création, `data` est un objet. Les champs courants sont `id` (l'identifiant de tâche généré par le système Kling, utilisé pour les requêtes ultérieures), `external_id` (l'écho de `options.external_task_id`, pouvant ne pas être renvoyé s'il n'est pas défini) et `status` (le statut de la tâche après création, généralement `submitted`). Dans la réponse d'interrogation, `data` est un tableau. Chaque tâche contient `id`, `external_id`, `status` (`submitted`, `processing`, `succeeded` ou `failed`), `message`, `create_time`, `update_time` et `outputs`. Les champs courants du résultat vidéo dans `outputs` sont `type`, `id`, `url`, `watermark_url` et `duration`. `url` est l'adresse du résultat sans filigrane, `watermark_url` est l'adresse du résultat avec filigrane, et `duration` est la durée de la vidéo en secondes. ## II. Texte vers vidéo ### 2.1 Créer une tâche ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo ``` Champs de la requête : | Champ | Type | Requis | Défaut / Plage de valeurs | Description | | - | - | - | - | - | | `prompt` | string | Oui | | Texte descriptif, peut contenir des descriptions positives et négatives ; 3072 caractères maximum, 2500 caractères recommandés | | `settings.resolution` | string | Non | Défaut `720p` ; `720p`, `1080p` | Résolution de la vidéo générée | | `settings.aspect_ratio` | string | Non | Défaut `16:9` ; `16:9`, `9:16`, `1:1` | Rapport d'aspect de la vidéo générée (largeur:hauteur) | | `settings.duration` | int | Non | Défaut 5 ; entier de 3 à 15 | Durée de la vidéo générée, en secondes | | `options.callback_url` | string | Non | | Adresse recevant les notifications de callback lors d'un changement de statut de la tâche | | `options.external_task_id` | string | Non | | Identifiant de tâche personnalisé ; ne remplace pas l'identifiant système, peut être utilisé pour interroger, doit être unique pour un utilisateur donné | | `options.watermark_info.enabled` | boolean | Non | Défaut `false` | Indique si un résultat avec filigrane doit être généré | La vidéo multi-plans est réalisée via le format fixe du champ `prompt` : « plan n, m, words ; plan n, m, words ; » (séparés par des caractères de ponctuation demi-largeur). `n` est le numéro du plan (6 maximum, 1 minimum), `m` est la durée du plan (chaque plan d'une durée d'au moins 1, la somme des durées de tous les plans est égale à la durée totale de la vidéo), et `words` est le prompt du plan (512 caractères maximum). ### 2.2 Exemple de création ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset", "settings": { "resolution": "1080p", "aspect_ratio": "16:9", "duration": 5 }, "options": { "external_task_id": "turbo-text-20260826-0001" } }' ``` Après une création réussie, l'identifiant de tâche est renvoyé : ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-text-task-id", "external_id": "turbo-text-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` Veuillez enregistrer `data.id`. Si `options.external_task_id` n'est pas fourni, `data.external_id` peut ne pas être renvoyé. ### 2.3 Interroger une tâche ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Veuillez utiliser la même clé API que lors de la création de la tâche. Vous pouvez également utiliser `external_task_ids` pour interroger un identifiant de tâche personnalisé. Vous devez renseigner `task_ids` ou `external_task_ids` — un seul des deux à chaque fois. Les deux acceptent de 1 à 50 identifiants séparés par des virgules anglaises ; `data` dans la réponse est un tableau et conserve l'ordre des identifiants de la requête. ### 2.4 Exemple de requête ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-text-task-id' \ -H 'Authorization: Bearer ' ``` Lorsque la tâche réussit, la réponse est : ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-text.mp4", "duration": 5 } ] } ] } ``` `status=processing` indique que la tâche est toujours en cours d'exécution ; il est recommandé d'interroger toutes les 10 à 30 secondes. `status=failed` indique que la tâche a échoué ; il ne faut plus continuer à interroger. Après la réussite de la tâche, enregistrez rapidement le fichier correspondant à `outputs[type=video].url`, car l'adresse de téléchargement peut avoir une durée de validité. ### 2.5 Informations de facturation ``` Coût de la tâche = prix unitaire par seconde de la résolution correspondante × settings.duration ``` Le palier de prix est déterminé uniquement par `settings.resolution` (`720p` ou `1080p`). Si `duration` n'est pas fourni, la facturation est basée sur la durée par défaut de 5 secondes. Lors de la création de la tâche, le montant est débité selon la durée demandée ; si la création de la tâche échoue ou si la génération finale échoue, les frais sont automatiquement remboursés. Les prix unitaires spécifiques sont ceux indiqués sur la page des prix du service que vous utilisez. ## III. Image vers vidéo ### 3.1 Créer une tâche ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo ``` Champs de la requête : | Champ | Type | Requis | Défaut / Plage de valeurs | Description | | - | - | - | - | - | | `contents` | array | Oui | | Ensemble des éléments de référence, contenant au moins un élément | | `contents[].type` | string | Oui | `prompt`, `first_frame` | Type d'élément : prompt ou image de première image | | `contents[].text` | string | Non | | Texte du prompt lorsque `type=prompt`, 2500 caractères maximum | | `contents[].url` | string | Non | | Image de première image lorsque `type=first_frame` ; prend en charge les URL et le Base64 | | `settings.resolution` | string | Non | Défaut `720p` ; `720p`, `1080p` | Résolution de la vidéo générée | | `settings.duration` | int | Non | Défaut 5 ; entier de 3 à 15 | Durée de la vidéo générée, en secondes | | `options.external_task_id` | string | Non | | Identifiant de tâche personnalisé ; ne remplace pas l'identifiant système, peut être utilisé pour interroger, doit être unique pour un utilisateur donné | | `options.watermark_info.enabled` | boolean | Non | Défaut `false` | Indique si un résultat avec filigrane doit être généré | Les images aux formats `.jpg`, `.jpeg` et `.png` sont acceptées ; le fichier ne doit pas dépasser 50 Mo, la largeur et la hauteur ne doivent pas être inférieures à 300 pixels, et le rapport largeur/hauteur doit être compris entre 1:2.5 et 2.5:1. L'image vers vidéo ne prend en charge que l'image de première image ; les modes « première image + dernière image » et « dernière image uniquement » ne sont pas pris en charge. `options.callback_url` peut également être transmis, avec la même utilisation que pour le texte vers vidéo. Les multi-plans sont également réalisés via le format fixe du champ `prompt`. ### 3.2 Exemple de création ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ { "type": "prompt", "text": "The subject turns toward the camera while the wind moves naturally through the scene" }, { "type": "first_frame", "url": "https://your-cdn.example.com/first-frame.png" } ], "settings": { "resolution": "1080p", "duration": 5 }, "options": { "external_task_id": "turbo-image-20260826-0001" } }' ``` En cas de succès, la réponse est : ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-image-task-id", "external_id": "turbo-image-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 3.3 Interroger une tâche Utilisez `data.id` de la réponse de création pour interroger la tâche : ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Lorsque vous interrogez avec `task_ids`, veuillez utiliser la même clé API que lors de la création de la tâche. Vous pouvez également utiliser `external_task_ids` pour interroger la valeur de `options.external_task_id` transmise à la création. Les paramètres de requête acceptent de 1 à 50 identifiants séparés par des virgules anglaises. ### 3.4 Exemple de requête ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-image-task-id' \ -H 'Authorization: Bearer ' ``` Lorsque la tâche réussit, l'adresse de la vidéo se trouve dans `outputs[type=video].url` : ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-image.mp4", "duration": 5 } ] } ] } ``` Lorsque `status=processing`, il est recommandé de continuer à interroger toutes les 10 à 30 secondes ; lorsque `status=failed`, arrêtez d'interroger et corrigez les entrées en fonction du message d'erreur. ### 3.5 Informations de facturation ``` Coût de la tâche = prix unitaire par seconde de la résolution correspondante × settings.duration ``` Le palier de prix est déterminé uniquement par `settings.resolution` (`720p` ou `1080p`). Si `duration` n'est pas fourni, la facturation est basée sur la durée par défaut de 5 secondes. Lors de la création de la tâche, le montant est débité selon la durée demandée ; si la création de la tâche échoue ou si la génération finale échoue, les frais sont automatiquement remboursés. Les prix unitaires spécifiques sont ceux indiqués sur la page des prix du service que vous utilisez. ## IV. Erreurs courantes et remarques Les erreurs d'interface utilisent la structure suivante : ```json theme={null} { "code": 1203, "message": "task not found (trace_id: platform-trace-id)", "request_id": "", "data": null } ``` Codes de statut courants : 400/1200 (paramètre ou type de contenu invalide, corrigez selon `message`), 401/1000 (clé API manquante ou invalide), 403/1103 (action non autorisée), 404/1203 (tâche inexistante ou non autorisée à interroger), 429/1302 (requêtes trop fréquentes, réduisez la fréquence et appliquez un backoff exponentiel), 500/5000, 503/5001, 504/5002 (erreur de service ou délai dépassé, réessayez plus tard, sans répéter les soumissions de manière incontrôlée). Si `message` contient `trace_id`, fournissez-le également lors de la prise de contact avec le support technique. Autres remarques : * Le corps de la requête n'a pas besoin d'ajouter `model` ou `model_name`, la version du modèle est déjà incluse dans l'URL. * Après la création de la tâche, persistez `data.id` ; ne considérez pas `request_id` comme l'identifiant de la tâche. * La taille maximale d'un corps de requête est de 64 Mo ; pour les images volumineuses, il est recommandé d'utiliser une URL publique accessible par Kling. * Les URL des éléments d'entrée doivent être accessibles publiquement par Kling ; elles ne doivent pas dépendre d'un réseau interne, de cookies ou d'un état de connexion temporaire. * Pour l'interrogation, utilisez un intervalle de 10 à 30 secondes et configurez un délai d'attente This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.