> ## 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 синхронізації губ Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Змусьте **наявне відео Kling** (5 секунд або 10 секунд) "говорити" відповідно до аудіо або тексту — тобто синхронізувати губи (Lip Sync). У поєднанні з `image2video` у `/kling/videos` (щоб оживити фотографію) можна створити повний процес "**фотографії, що говорять / цифрового ведучого**".

> Цей інтерфейс є зручним однокроковим обгортанням, наданим AceDataCloud, для поширених сценаріїв, керованих аудіо/текстом; він не є дзеркалом полів багатокрокового офіційного інтерфейсу Kling «розпізнавання обличчя → Advanced Lip Sync». Будь ласка, керуйтеся таблицею параметрів на цій сторінці.

* **Адреса інтерфейсу**：`POST https://api.acedata.cloud/kling/lip-sync`
* **Формат запиту**：`application/json`
* **Формат відповіді**：`application/json`
* **Тарифікація**：кожен успішний виклик **2.45 Credits**（фіксовано）

## Заголовки запиту（Request Headers）

| Поле | Значення | Опис |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Ваш API-ключ, [отримати тут](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Формат тіла запиту |
| `accept` | `application/json` | Формат відповіді |

## Параметри запиту（Request Body）

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
| - | - | - | - | - |
| `mode` | string | Так | — | Режим генерації. Перелік: `audio2video`（керування аудіо）、`text2video`（керування текстом） |
| `video_id` | string | один з двох | — | ID відео, згенерованого Kling（наприклад, `video_id`, повернений image2video з `/kling/videos`）。**Підтримуються лише відео 5s/10s, згенеровані протягом 30 днів**。`video_id` та `video_url` — один з двох, не можна передавати одночасно |
| `video_url` | string | один з двох | — | Загальнодоступне посилання на відео。Обмеження：`.mp4`/`.mov`，≤100MB，тривалість 2–10s，лише 720p/1080p，довжина сторони 720–1920px。Один з двох із `video_id` |
| `audio_url` | string | умовно | — | URL для завантаження аудіо керування, обов’язковий при `audio2video` + `audio_type=url`。Формати `.mp3`/`.wav`/`.m4a`/`.aac`，≤5MB |
| `audio_type` | string | Ні | `url` | Спосіб передавання аудіо。Перелік：`url`、`file`（діє для `audio2video`） |
| `audio_file` | string | умовно | — | Base64 аудіофайлу, обов’язковий при `audio_type=file`。Формат як вище，≤5MB |
| `text` | string | умовно | — | Текст для озвучення, обов’язковий для `text2video`，**максимум 120 символів** |
| `voice_id` | string | умовно | — | ID голосу, обов’язковий для `text2video` |
| `voice_language` | string | Ні | `zh` | Мова голосу。Перелік：`zh`、`en`（діє для `text2video`） |
| `voice_speed` | float | Ні | `1.0` | Швидкість мовлення, діапазон `0.8`–`2.0`, з точністю до одного знака після коми（діє для `text2video`） |
| `callback_url` | string | Ні | — | Адреса зворотного виклику。Передавання цього параметра або `async=true` означає **асинхронний режим**：негайно повертається `task_id`, після генерації результат надсилається через зворотний виклик |
| `async` | boolean | Ні | `false` | Чи є запит асинхронним。При `true` негайно повертається `task_id`, використовуйте разом з опитуванням `/kling/tasks` або зворотним викликом `callback_url` |

## Приклади запитів

### 1）Керування аудіо（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）Керування текстом（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
  }'
```

## Приклад відповіді（синхронний успіх）

```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"
}
```

| Поле | Тип | Опис |
| - | - | - |
| `success` | boolean | Чи успішно |
| `task_id` | string | ID цього завдання（можна використовувати для запиту `/kling/tasks`） |
| `video_id` | string | ID Kling згенерованого відео（може бути вхідними даними для наступного `extend`/`lip-sync`） |
| `video_url` | string | URL згенерованого відео, що говорить（збережено на CDN цієї платформи, дійсний довгостроково） |
| `duration` | string | Тривалість відео（секунди） |
| `state` | string | Стан завдання：`succeed` / `failed` |

## Асинхронний режим і запит

Коли передається `callback_url` або `async: true`, інтерфейс **негайно повертає** `task_id`; після цього можна:

* **Опитування**：`POST /kling/tasks`，body `{ "action": "retrieve", "id": "<task_id>" }`（безкоштовно）
* **Зворотний виклик**：після завершення генерації результат надсилається POST-запитом на ваш `callback_url`

## Повний процес：фотографія, що говорить（image2video → lip-sync）

```bash theme={null}
# Крок 1: оживіть фото, отримайте 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", ... }

# Крок 2: синхронізуйте губи з аудіо
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", ... }
```

## Відповідь з помилкою

```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 | Значення |
| - | - | - |
| 400 | `bad_request` | Відсутні або недійсні параметри (наприклад, не передано mode, конфлікт вибору між video та audio, text перевищує 120 символів) |
| 401 | `authorization_missing` | Відсутній або недійсний API-ключ |
| 403 | `forbidden` | Вміст заблоковано системою контролю ризиків |
| 429 | `too_many_requests` | Обмеження паралельних запитів на стороні постачальника, повторіть спробу пізніше |
| 500 | `api_error` | Помилка на стороні постачальника або внутрішня помилка |

## Примітки

* `video_id` має бути згенерованим відео Kling протягом **останніх 30 днів** і мати тривалість **5 с або 10 с**; інакше передайте відео, що відповідає обмеженням, через `video_url`.
* Для вхідного відео рекомендується **чітке обличчя анфас, одна людина** — це забезпечує найкращий ефект синхронізації губ.
* Тривалість аудіо/тексту має відповідати тривалості відео (аудіо не має перевищувати довжину відео).
* Оплата стягується у разі **успіху** (2.45 Credits/раз); за помилки перевірки параметрів (4xx) оплата не стягується.


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