> ## 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.

# Kling-Lip-Sync-API (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Lasse ein **bereits vorhandenes Kling-Video** (5 Sekunden oder 10 Sekunden) anhand von Audio oder Text „sprechen“ – also lippensynchron (Lip Sync). In Kombination mit `image2video` von `/kling/videos` (um Fotos zu animieren) lässt sich daraus ein vollständiger Ablauf für „**sprechende Fotos / digitale Personenansagen**“ erstellen.

> Diese Schnittstelle ist eine von AceDataCloud bereitgestellte praktische Einzelschritt-Kapselung für gängige audio-/textgesteuerte Szenarien; sie ist keine Feldspiegelung der mehrstufigen offiziellen Kling-Schnittstelle „Gesichtserkennung → Advanced Lip Sync“. Bitte orientiere dich an der Parametertabelle auf dieser Seite.

* **Schnittstellenadresse**: `POST https://api.acedata.cloud/kling/lip-sync`
* **Anfrageformat**: `application/json`
* **Antwortformat**: `application/json`
* **Abrechnung**: Pro erfolgreichem Aufruf **2.45 Credits** (fest)

## Anfrage-Header (Request Headers)

| Feld | Wert | Beschreibung |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Dein API-Schlüssel, [hier erhalten](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Format des Anfragebodys |
| `accept` | `application/json` | Antwortformat |

## Anfrageparameter (Request Body)

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| - | - | - | - | - |
| `mode` | string | Ja | — | Generierungsmodus. Aufzählung: `audio2video` (audiogesteuert), `text2video` (textgesteuert) |
| `video_id` | string | Eines von beiden | — | ID eines von Kling generierten Videos (z. B. die von image2video aus `/kling/videos` zurückgegebene `video_id`). **Unterstützt nur innerhalb der letzten 30 Tage generierte 5s-/10s-Videos**. `video_id` und `video_url` sind alternativ, sie können nicht gleichzeitig übergeben werden |
| `video_url` | string | Eines von beiden | — | Öffentlich zugänglicher Videolink. Einschränkungen: `.mp4`/`.mov`, ≤100MB, Dauer 2–10s, nur 720p/1080p, Kantenlänge 720–1920px. Alternativ zu `video_id` |
| `audio_url` | string | Bedingt | — | Download-URL des steuernden Audios, erforderlich bei `audio2video` + `audio_type=url`. Formate `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | Nein | `url` | Audioübertragungsmethode. Aufzählung: `url`, `file` (wirksam bei `audio2video`) |
| `audio_file` | string | Bedingt | — | Base64 der Audiodatei, erforderlich bei `audio_type=file`. Gleiches Format wie oben, ≤5MB |
| `text` | string | Bedingt | — | Vorzulesender Text, erforderlich bei `text2video`, **maximal 120 Zeichen** |
| `voice_id` | string | Bedingt | — | Stimmfarben-ID, erforderlich bei `text2video` |
| `voice_language` | string | Nein | `zh` | Sprache der Stimmfarbe. Aufzählung: `zh`, `en` (wirksam bei `text2video`) |
| `voice_speed` | float | Nein | `1.0` | Sprechgeschwindigkeit, Bereich `0.8`–`2.0`, auf eine Dezimalstelle genau (wirksam bei `text2video`) |
| `callback_url` | string | Nein | — | Callback-Adresse. Bei Übergabe dieses Werts oder bei `async=true` gilt der **asynchrone Modus**: `task_id` wird sofort zurückgegeben, Callback nach der Ergebnisgenerierung |
| `async` | boolean | Nein | `false` | Ob asynchron. Bei `true` wird `task_id` sofort zurückgegeben, in Kombination mit `/kling/tasks` zum Polling oder `callback_url` für Callbacks |

## Anfragebeispiele

### 1）Audiogesteuert (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）Textgesteuert (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
  }'
```

## Antwortbeispiel (synchroner Erfolg)

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

| Feld | Typ | Beschreibung |
| - | - | - |
| `success` | boolean | Ob erfolgreich |
| `task_id` | string | ID dieser Aufgabe (kann für Abfragen über `/kling/tasks` verwendet werden) |
| `video_id` | string | Kling-ID des generierten Videos (kann als Eingabe für das nächste `extend`/`lip-sync` verwendet werden) |
| `video_url` | string | URL des generierten sprechenden Videos (bereits im CDN dieser Plattform gespeichert, langfristig gültig) |
| `duration` | string | Videodauer (Sekunden) |
| `state` | string | Aufgabenstatus: `succeed` / `failed` |

## Asynchroner Modus und Abfrage

Bei Übergabe von `callback_url` oder `async: true` gibt die Schnittstelle **sofort** `task_id` zurück; anschließend kannst du:

* **Pollen**: `POST /kling/tasks`, Body `{ "action": "retrieve", "id": "<task_id>" }` (kostenlos)
* **Callback**: Nach Abschluss der Generierung wird das Ergebnis per POST an deine `callback_url` gesendet

## Vollständiger Ablauf: Sprechendes Foto (image2video → lip-sync)

```bash theme={null}
# Schritt 1: Das Foto animieren, um die video_id zu erhalten
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", ... }

# Schritt 2: Mit Audio lippensynchronisieren
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", ... }
```

## Fehlerantwort

```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 | Bedeutung |
| - | - | - |
| 400 | `bad_request` | Parameter fehlen oder sind ungültig (z. B. mode nicht übergeben, Konflikt bei der Auswahl zwischen video und audio, text überschreitet 120 Zeichen) |
| 401 | `authorization_missing` | API-Schlüssel fehlt oder ist ungültig |
| 403 | `forbidden` | Inhalt wurde durch die Risikokontrolle abgefangen |
| 429 | `too_many_requests` | Upstream-Parallelitätslimit, bitte später erneut versuchen |
| 500 | `api_error` | Upstream- oder interner Fehler |

## Hinweise

* `video_id` muss ein innerhalb von **30 Tagen** generiertes Kling-Video sein und **5 s oder 10 s** lang sein; andernfalls bitte `video_url` verwenden, um ein Video zu übergeben, das den Einschränkungen entspricht.
* Für das Eingabevideo werden ein **klares frontales Gesicht und eine einzelne Person** empfohlen, um den besten Lippensynchronisationseffekt zu erzielen.
* Die Audio-/Textdauer sollte der Videodauer entsprechen (Audio darf die Videolänge nicht überschreiten).
* Die Abrechnung erfolgt bei **Erfolg** (2,45 Credits/Vorgang); bei fehlgeschlagener Parameterprüfung (4xx) fallen keine Kosten an.


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