> ## 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». Ориентируйтесь на таблицу параметров на этой странице.

* **Адрес API**: `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`). **Поддерживаются только видео длительностью 5/10 с, созданные в течение последних 30 дней**. Выберите один из `video_id` и `video_url`; одновременно передавать нельзя |
| `video_url` | string | Один из двух | — | Ссылка на общедоступное видео. Ограничения: `.mp4`/`.mov`, ≤100 МБ, длительность 2–10 с, только 720p/1080p, размер стороны 720–1920 px. Выберите один из двух с `video_id` |
| `audio_url` | string | Условно | — | URL для скачивания управляющего аудио, обязателен при `audio2video` + `audio_type=url`. Форматы `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5 МБ |
| `audio_type` | string | Нет | `url` | Способ передачи аудио. Перечисление: `url`, `file` (действует при `audio2video`) |
| `audio_file` | string | Условно | — | Base64 аудиофайла, обязателен при `audio_type=file`. Форматы те же, ≤5 МБ |
| `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.