> ## 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 & 3.0 Omni

Les paramètres et leur utilisation sont alignés sur la documentation officielle. Les paramètres détaillés peuvent être consultés directement dans la documentation officielle.

## 1. Vue d'ensemble

Ce document explique comment utiliser les capacités de texte vers vidéo, image vers vidéo, vidéo Omni et contrôle de mouvement via le protocole natif Kling 3.0.

Les quatre capacités utilisent le mode de tâche asynchrone :

1. Appeler l'interface de création correspondante.
2. Conserver `data.id` de la réponse de création.
3. Utiliser la même clé API que celle utilisée lors de la création de la tâche pour interroger le statut.
4. Une fois la tâche réussie, récupérer et conserver la vidéo générée depuis `outputs`.

### 1.1 Adresses des interfaces

| Capacité | Création de tâche | Interrogation de tâche |
| - | - | - |
| Texte vers vidéo | `POST /v3/kling/text-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Image vers vidéo | `POST /v3/kling/image-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Vidéo Omni | `POST /v3/kling/omni-video/kling-3.0-omni` | `GET /v3/kling/tasks` |
| Contrôle de mouvement | `POST /v3/kling/motion-control/kling-3.0` | `GET /v3/kling/tasks` |

Les adresses complètes des exemples dans ce document sont constituées de `https://{api_domain}` suivi du chemin d'interface indiqué dans le tableau, où `{api_domain}` correspond au domaine API que vous utilisez.

### 1.2 Authentification

Toutes les requêtes doivent inclure la clé API. Les requêtes POST doivent également spécifier le type de contenu JSON :

```
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 1.3 Structure de réponse

`data` dans la réponse de création est un objet. Les champs courants sont les suivants :

| Champ | Type | Description |
| - | - | - |
| `id` | string | Identifiant de tâche généré par le système Kling, utilisé pour l'interrogation ultérieure |
| `external_id` | string | Écho de `options.external_task_id` ; peut ne pas être renvoyé s'il n'est pas défini |
| `status` | string | Statut de la tâche après création, généralement `submitted` |

`data` dans la réponse d'interrogation est un tableau. Chaque tâche comprend les champs suivants :

| Champ | Type | Description |
| - | - | - |
| `id` | string | Identifiant de tâche généré par le système |
| `external_id` | string | Identifiant de tâche personnalisé de l'appelant (le cas échéant) |
| `status` | string | `submitted`, `processing`, `succeeded` ou `failed` |
| `message` | string | Informations sur le statut de la tâche ; en cas d'échec, contient la raison (le cas échéant) |
| `create_time` | integer | Heure de création, horodatage Unix en millisecondes (le cas échéant) |
| `update_time` | integer | Heure de mise à jour, horodatage Unix en millisecondes (le cas échéant) |
| `outputs` | array | Résultats générés ; une tâche réussie contient généralement un résultat `type=video` |

Le résultat vidéo dans `outputs` contient généralement les champs `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).

## 2. Texte vers vidéo

Documentation officielle des paramètres : Text to Video

### 2.1 Création de tâche

```
POST https://{api_domain}/v3/kling/text-to-video/kling-3.0
```

Champs de requête courants :

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `prompt` | string | Oui | Invite de génération vidéo, ne peut pas être vide, maximum 3072 caractères |
| `settings.multi_shot` | boolean | Non | Indique s'il faut générer une vidéo multi-plans, défaut `true` |
| `settings.resolution` | string | Non | `720p`, `1080p` ou `4k`, défaut `720p` |
| `settings.aspect_ratio` | string | Non | `16:9`, `9:16` ou `1:1`, défaut `16:9` |
| `settings.audio` | string | Non | `off` ou `native`, défaut `off` |
| `settings.duration` | integer | Non | 3–15 secondes, défaut 5 secondes |
| `options.callback_url` | string | Non | Adresse pour recevoir les notifications de changement de statut de la tâche |
| `options.external_task_id` | string | Non | Identifiant de tâche personnalisé |
| `options.watermark_info.enabled` | boolean | Non | Indique s'il faut générer un résultat avec filigrane, défaut `false` |

Lorsque `multi_shot=true`, vous pouvez décrire les plans multiples dans l'invite selon le format officiel Kling ; la somme des durées de chaque plan doit être égale à la durée totale de la vidéo.

### 2.2 Exemple de création

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -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",
      "duration": 5,
      "audio": "native"
    },
    "options": {
      "external_task_id": "text-video-20260826-0001"
    }
  }'
```

Après création, l'identifiant de tâche est renvoyé :

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-text-task-id",
    "external_id": "text-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 2.3 Interrogation de tâche

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

Veuillez conserver `data.id`. Si `options.external_task_id` n'est pas fourni, `data.external_id` peut ne pas être renvoyé.

Veuillez utiliser la même clé API que celle utilisée lors de la création de la tâche. Si l'identifiant de tâche n'existe pas ou n'est pas accessible, `task not found` est renvoyé.

Vous pouvez également utiliser `external_task_ids` pour interroger un identifiant de tâche personnalisé :

```
GET https://{api_domain}/v3/kling/tasks?external_task_ids={external_task_id}
```

`task_ids` et `external_task_ids` doivent être renseignés un seul à la fois. Les deux acceptent 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 d'interrogation

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-text-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

Retour en cas de succès :

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-text-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/text-video.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é et qu'il ne faut pas continuer à interroger. Une fois la tâche réussie, veuillez sauvegarder rapidement le fichier correspondant à `outputs[type=video].url` ; 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 par seconde du niveau correspondant à la résolution et au format audio × settings.duration
```

Le niveau de prix est déterminé par `settings.resolution` et `settings.audio`. Par exemple, pour `1080p`, `audio=native`, `duration=5`, le coût est « prix par seconde du niveau audio natif 1080p × 5 secondes ». Si `duration` n'est pas fourni, la facturation se fait sur la valeur par défaut de 5 secondes.

Le débit est effectué au moment de la création de la tâche selon la durée demandée ; si la création échoue ou si la génération finale échoue, les frais sont automatiquement remboursés. Le prix unitaire spécifique est indiqué sur la page des prix du service que vous utilisez.

## 3. Image vers vidéo

Documentation officielle des paramètres : Image to Video

### 3.1 Création de tâche

```
POST https://{api_domain}/v3/kling/image-to-video/kling-3.0
```

Champs de requête courants :

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `contents` | array | Oui | Liste de contenus multimodaux, au moins un élément |
| `contents[].type` | string | Oui | `prompt`, `first_frame`, `last_frame` ou `element` |
| `settings.resolution` | string | Non | `720p`, `1080p` ou `4k`, défaut `720p` |
| `settings.multi_shot` | boolean | Non | Indique s'il faut générer une vidéo multi-plans, défaut `true` |
| `settings.audio` | string | Non | `off` ou `native`, défaut `off` |
| `settings.duration` | integer | Non | 3–15 secondes, défaut 5 secondes |
| `options.callback_url` | string | Non | Adresse pour recevoir les notifications de changement de statut de la tâche |
| `options.external_task_id` | string | Non | Identifiant de tâche personnalisé |
| `options.watermark_info.enabled` | boolean | Non | Indique s'il faut générer un résultat avec filigrane, défaut `false` |

Champs des sous-éléments de `contents` :

| type | Champs obligatoires | Description |
| - | - | - |
| `prompt` | `text` | Invite textuelle, maximum 3072 caractères |
| `first_frame` | `url` | Image du premier plan, prend en charge URL ou Base64 ; doit être fournie |
| `last_frame` | `url` | Image du dernier plan, prend en charge URL ou Base64 ; uniquement le dernier plan n'est pas pris en charge, le premier plan doit également être fourni |
| `element` | `element_id`, `id` | Identifiant du sujet et identifiant d'index utilisé pour référencer le sujet dans l'invite ; `id` ne doit pas être dupliqué dans la même tâche ; maximum 3 sujets spécifiés |

Les images prennent en charge `.jpg`, `.jpeg` et `.png`, taille maximale de 50 Mo, hauteur et largeur minimales de 300 pixels, rapport hauteur/largeur compris entre 1:2.5 et 2.5:1.

### 3.2 Exemple de création

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -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,
      "audio": "off"
    },
    "options": {
      "external_task_id": "image-video-20260826-0001"
    }
  }'
```

En cas de succès, `data.id` est l'identifiant de tâche à utiliser pour l'interrogation ultérieure :

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-image-task-id",
    "external_id": "image-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 3.3 Interrogation de 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}
```

Lors de l'interrogation par `task_ids`, veuillez utiliser la même clé API que celle utilisée lors de la création. Vous pouvez également interroger `options.external_task_id` via `external_task_ids`. Le paramètre d'interrogation accepte 1 à 50 identifiants séparés par des virgules anglaises.

### 3.4 Exemple d'interrogation

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-image-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

En cas de succès, l'adresse vidéo se trouve dans `outputs[type=video].url` :

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-image-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/image-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

Lorsque `status=processing`, il est recommandé de continuer à interroger toutes les 10 à 30 secondes ; lorsque `status=failed`, arrêtez l'interrogation et corrigez l'entrée en fonction du message d'erreur.

### 3.5 Informations de facturation

```
Coût de la tâche = prix par seconde du niveau correspondant à la résolution et au format audio × settings.duration
```

Le niveau de prix est déterminé par `settings.resolution` et `settings.audio`. Si `duration` n'est pas fourni, la facturation se fait sur la valeur par défaut de 5 secondes. Le débit est effectué au moment de la création selon la durée demandée ; si la création échoue ou si la génération finale échoue, les frais sont automatiquement remboursés. Le prix unitaire spécifique est indiqué sur la page des prix du service que vous utilisez.

## 4. Vidéo Omni

Documentation officielle des paramètres : Omni Video

### 4.1 Création de tâche

```
POST https://{api_domain}/v3/kling/omni-video/kling-3.0-omni
```

Champs de requête courants :

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `contents` | array | Oui | Liste de contenus multimodaux, au moins un élément |
| `contents[].type` | string | Oui | `prompt`, `first_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video` ou `element` |
| `settings.resolution` | string | Non | `720p`, `1080p` ou `4k`, défaut `720p` |
| `settings.multi_shot` | boolean | Non | Indique s'il faut générer une vidéo multi-plans, défaut `true` |
| `settings.aspect_ratio` | string | Non | `16:9`, `9:16` ou `1:1`, défaut `16:9` ; obligatoire s'il n'y a pas d'image de premier plan ni de vidéo de |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.