> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API de synchronisation labiale Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Faites « parler » une **vidéo Kling existante** (5 secondes ou 10 secondes) selon un audio ou un texte — c’est-à-dire synchroniser les lèvres (Lip Sync). Associée à `image2video` de `/kling/videos` (pour animer une photo), elle permet de former un flux complet de « **photo parlante / présentateur numérique** ».

> Cette interface est un encapsulage pratique en une étape fourni par AceDataCloud, destiné aux scénarios courants pilotés par audio/texte ; elle n’est pas un miroir des champs de l’interface officielle Kling en plusieurs étapes « reconnaissance faciale → Advanced Lip Sync ». Veuillez vous référer au tableau des paramètres de cette page.

* **Adresse de l’interface** : `POST https://api.acedata.cloud/kling/lip-sync`
* **Format de requête** : `application/json`
* **Format de réponse** : `application/json`
* **Facturation** : **2.45 Credits** par appel réussi (fixe)

## En-têtes de requête (Request Headers)

| Champ | Valeur | Description |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Votre clé API, [obtenir ici](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Format du corps de la requête |
| `accept` | `application/json` | Format de réponse |

## Paramètres de requête (Request Body)

| Paramètre | Type | Obligatoire | Par défaut | Description |
| - | - | - | - | - |
| `mode` | string | Oui | — | Mode de génération. Énumération : `audio2video` (piloté par audio), `text2video` (piloté par texte) |
| `video_id` | string | Un sur deux | — | ID d’une vidéo générée par Kling (par exemple, le `video_id` renvoyé par image2video de `/kling/videos`). **Prend uniquement en charge les vidéos de 5 s/10 s générées au cours des 30 derniers jours**. Choisissez entre `video_id` et `video_url`, ne les transmettez pas simultanément |
| `video_url` | string | Un sur deux | — | Lien vidéo accessible publiquement. Contraintes : `.mp4`/`.mov`, ≤100MB, durée de 2–10s, uniquement 720p/1080p, longueur de côté 720–1920px. Choisissez entre cette option et `video_id` |
| `audio_url` | string | Conditionnel | — | URL de téléchargement de l’audio pilote, obligatoire lorsque `audio2video` + `audio_type=url`. Formats `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | Non | `url` | Méthode de transmission audio. Énumération : `url`, `file` (prend effet avec `audio2video`) |
| `audio_file` | string | Conditionnel | — | Base64 du fichier audio, obligatoire lorsque `audio_type=file`. Même format que ci-dessus, ≤5MB |
| `text` | string | Conditionnel | — | Texte à lire, obligatoire avec `text2video`, **120 caractères maximum** |
| `voice_id` | string | Conditionnel | — | ID de la voix, obligatoire avec `text2video` |
| `voice_language` | string | Non | `zh` | Langue de la voix. Énumération : `zh`, `en` (prend effet avec `text2video`) |
| `voice_speed` | float | Non | `1.0` | Vitesse de parole, plage `0.8`–`2.0`, précise à une décimale (prend effet avec `text2video`) |
| `callback_url` | string | Non | — | Adresse de rappel. En transmettant cette option ou `async=true`, vous activez le **mode asynchrone** : renvoie immédiatement `task_id`, puis effectue un rappel une fois le résultat généré |
| `async` | boolean | Non | `false` | Indique si l’opération est asynchrone. Lorsque `true`, renvoie immédiatement `task_id`, à utiliser avec l’interrogation de `/kling/tasks` ou le rappel `callback_url` |

## Exemples de requêtes

### 1）Piloté par audio (audio2video)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "audio2video",
    "video_id": "895055164389466178",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }'
```

### 2）Piloté par texte (text2video)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "text2video",
    "video_id": "895055164389466178",
    "text": "哥，好久不见，我一切都好，你要照顾好自己。",
    "voice_id": "genshin_vindi2",
    "voice_language": "zh",
    "voice_speed": 1.0
  }'
```

## Exemple de réponse (succès synchrone)

```json theme={null}
{
  "success": true,
  "task_id": "07a3ec65-9f7e-4a09-b7b7-282684082527",
  "video_id": "895055968777281546",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "4.966",
  "state": "succeed"
}
```

| Champ | Type | Description |
| - | - | - |
| `success` | boolean | Indique si l’opération a réussi |
| `task_id` | string | ID de cette tâche (peut être utilisé pour une requête via `/kling/tasks`) |
| `video_id` | string | ID Kling de la vidéo générée (peut servir d’entrée pour le prochain `extend`/`lip-sync`) |
| `video_url` | string | URL de la vidéo parlante générée (archivée sur le CDN de cette plateforme, valide à long terme) |
| `duration` | string | Durée de la vidéo (secondes) |
| `state` | string | État de la tâche : `succeed` / `failed` |

## Mode asynchrone et consultation

Lorsque `callback_url` ou `async: true` est transmis, l’interface **renvoie immédiatement** `task_id` ; vous pouvez ensuite :

* **Interroger** : `POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (gratuit)
* **Rappel** : une fois la génération terminée, le résultat est envoyé par POST à votre `callback_url`

## Flux complet : photo parlante (image2video → lip-sync)

```bash theme={null}
# Étape 1 : animez la photo, obtenez video_id
curl -X POST 'https://api.acedata.cloud/kling/videos' \
  -H 'authorization: Bearer ${API_KEY}' -H 'content-type: application/json' \
  -d '{"model":"kling-v2-1-master","action":"image2video","start_image_url":"https://cdn.acedata.cloud/4hfydw.jpg","prompt":"look at camera, natural","duration":5,"mode":"pro"}'
# → { "video_id": "895055164389466178", ... }

# Étape 2 : synchronisez les lèvres avec l'audio
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' -H 'content-type: application/json' \
  -d '{"mode":"audio2video","video_id":"895055164389466178","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"}'
# → { "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4", ... }
```

## Réponse d'erreur

```json theme={null}
{
  "success": false,
  "error": { "code": "bad_request", "message": "one of video_id or video_url is required" },
  "trace_id": "f07cab09-3c18-4d74-9030-64ee840d9f16",
  "task_id": "f490537f-2e5c-4739-8149-6252fba2091c"
}
```

| HTTP | code | Signification |
| - | - | - |
| 400 | `bad_request` | Paramètres manquants ou invalides (par exemple, mode non fourni, conflit entre video et audio dont un seul doit être sélectionné, text dépasse 120 caractères) |
| 401 | `authorization_missing` | Clé API manquante ou invalide |
| 403 | `forbidden` | Contenu bloqué par le contrôle des risques |
| 429 | `too_many_requests` | Limitation de concurrence en amont, veuillez réessayer plus tard |
| 500 | `api_error` | Erreur en amont ou interne |

## Remarques

* `video_id` doit être une vidéo Kling générée dans les **30 jours**, et durer **5 s ou 10 s** ; sinon, utilisez `video_url` pour fournir une vidéo conforme aux contraintes.
* Il est recommandé que la vidéo d'entrée montre un **visage net de face, une seule personne**, afin d'obtenir le meilleur effet de synchronisation labiale.
* La durée de l'audio/du texte doit correspondre à celle de la vidéo (l'audio ne doit pas dépasser la durée de la vidéo).
* La facturation a lieu en cas de **succès** (2,45 Credits/fois) ; les échecs de validation des paramètres (4xx) ne sont pas facturés.


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