> ## 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 synchronizacji ruchu warg Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Spraw, aby **istniejący film Kling** (5 lub 10 sekund) „mówił” zgodnie z dźwiękiem lub tekstem — czyli synchronizował ruch warg (Lip Sync). W połączeniu z `image2video` z `/kling/videos` (ożywianie zdjęcia) można stworzyć kompletny proces „**mówiącego zdjęcia / cyfrowego prezentera**”.

> Ten interfejs jest wygodnym, jednoetapowym opakowaniem udostępnianym przez AceDataCloud, przeznaczonym dla typowych scenariuszy sterowanych dźwiękiem/tekstem; nie jest odwzorowaniem pól wieloetapowego oficjalnego interfejsu Kling „rozpoznawanie twarzy → Advanced Lip Sync”. Należy kierować się tabelą parametrów na tej stronie.

* **Adres interfejsu**：`POST https://api.acedata.cloud/kling/lip-sync`
* **Format żądania**：`application/json`
* **Format odpowiedzi**：`application/json`
* **Rozliczenie**：**2.45 Credits** za każde pomyślne wywołanie (stałe)

## Nagłówki żądania（Request Headers）

| Pole | Wartość | Opis |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Twój klucz API, [pobierz tutaj](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Format treści żądania |
| `accept` | `application/json` | Format odpowiedzi |

## Parametry żądania（Request Body）

| Parametr | Typ | Wymagane | Domyślnie | Opis |
| - | - | - | - | - |
| `mode` | string | Tak | — | Tryb generowania. Wyliczenie: `audio2video` (sterowanie dźwiękiem), `text2video` (sterowanie tekstem) |
| `video_id` | string | Jedno z dwóch | — | ID filmu wygenerowanego przez Kling (np. `video_id` zwrócone przez image2video z `/kling/videos`). **Obsługiwane są tylko filmy 5s/10s wygenerowane w ciągu ostatnich 30 dni**. Należy podać jedno z `video_id` i `video_url`; nie można przekazać obu jednocześnie |
| `video_url` | string | Jedno z dwóch | — | Publicznie dostępny link do filmu. Ograniczenia: `.mp4`/`.mov`, ≤100MB, długość 2–10s, tylko 720p/1080p, długość boku 720–1920px. Należy podać jedno z `video_id` i `video_url` |
| `audio_url` | string | Warunkowo | — | URL pobierania dźwięku sterującego, wymagany przy `audio2video` + `audio_type=url`. Format `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | Nie | `url` | Metoda przesyłania dźwięku. Wyliczenie: `url`, `file` (obowiązuje przy `audio2video`) |
| `audio_file` | string | Warunkowo | — | Base64 pliku dźwiękowego, wymagany przy `audio_type=file`. Format jak wyżej, ≤5MB |
| `text` | string | Warunkowo | — | Tekst do odczytania, wymagany przy `text2video`, **maksymalnie 120 znaków** |
| `voice_id` | string | Warunkowo | — | ID głosu, wymagane przy `text2video` |
| `voice_language` | string | Nie | `zh` | Język głosu. Wyliczenie: `zh`, `en` (obowiązuje przy `text2video`) |
| `voice_speed` | float | Nie | `1.0` | Tempo mowy, zakres `0.8`–`2.0`, z dokładnością do jednego miejsca po przecinku (obowiązuje przy `text2video`) |
| `callback_url` | string | Nie | — | Adres zwrotny. Przekazanie tej wartości lub `async=true` oznacza **tryb asynchroniczny**: natychmiast zwracane jest `task_id`, a po wygenerowaniu wyniku następuje wywołanie zwrotne |
| `async` | boolean | Nie | `false` | Czy asynchronicznie. Gdy `true`, natychmiast zwracane jest `task_id`; użyj odpytywania `/kling/tasks` lub wywołania zwrotnego `callback_url` |

## Przykłady żądań

### 1）Sterowanie dźwiękiem（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）Sterowanie tekstem（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
  }'
```

## Przykład odpowiedzi（synchronizacja zakończona powodzeniem）

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

| Pole | Typ | Opis |
| - | - | - |
| `success` | boolean | Czy operacja się powiodła |
| `task_id` | string | ID bieżącego zadania (może być używane do zapytań przez `/kling/tasks`) |
| `video_id` | string | ID Kling wygenerowanego filmu (może być użyte jako dane wejściowe kolejnego `extend`/`lip-sync`) |
| `video_url` | string | URL wygenerowanego filmu z mową (zapisany na CDN tej platformy, ważny długoterminowo) |
| `duration` | string | Długość filmu (sekundy) |
| `state` | string | Status zadania: `succeed` / `failed` |

## Tryb asynchroniczny i zapytania

Po przekazaniu `callback_url` lub `async: true` interfejs **natychmiast zwraca** `task_id`; następnie można:

* **Odpytywać**：`POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (bezpłatnie)
* **Wywołanie zwrotne**：po zakończeniu generowania wynik zostanie wysłany metodą POST do Twojego `callback_url`

## Pełny proces: mówiące zdjęcie（image2video → lip-sync）

```bash theme={null}
# Krok 1: ożyw zdjęcie, uzyskaj 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":"spójrz w kamerę, naturalnie","duration":5,"mode":"pro"}'
# → { "video_id": "895055164389466178", ... }

# Krok 2: zsynchronizuj ruch ust z dźwiękiem
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", ... }
```

## Odpowiedź błędu

```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 | Znaczenie |
| - | - | - |
| 400 | `bad_request` | Brakujący lub nieprawidłowy parametr (np. nie przekazano mode, konflikt wyboru między video a audio, text przekracza 120 znaków) |
| 401 | `authorization_missing` | Brakujący lub nieprawidłowy klucz API |
| 403 | `forbidden` | Treść zablokowana przez kontrolę ryzyka |
| 429 | `too_many_requests` | Limit równoczesnych żądań po stronie upstream, spróbuj ponownie później |
| 500 | `api_error` | Błąd upstream lub wewnętrzny |

## Uwagi

* `video_id` musi być filmem Kling wygenerowanym w ciągu **30 dni** i mieć długość **5 s lub 10 s**; w przeciwnym razie użyj `video_url`, aby przekazać film spełniający ograniczenia.
* Zaleca się, aby wejściowy film przedstawiał **wyraźną twarz en face, jedną osobę**, co zapewnia najlepszy efekt ruchu ust.
* Długość dźwięku/tekstu powinna odpowiadać długości filmu (dźwięk nie może być dłuższy niż film).
* Opłata jest naliczana przy **sukcesie** (2,45 Credits/raz); nieudana walidacja parametrów (4xx) nie jest płatna.


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