> ## 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 läppsynk-API (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Låt en **befintlig Kling-video** (5 sekunder eller 10 sekunder) "tala" enligt ljud eller text — dvs. läppsynka (Lip Sync). Tillsammans med `image2video` i `/kling/videos` (som får foton att röra sig) kan detta kopplas ihop till ett komplett flöde för "**talande foton / digitala presentatörer**".

> Detta API är en smidig enstegsförpackning från AceDataCloud, avsedd för vanliga ljud-/textdrivna scenarier; det är inte en fältspegel av Klings officiella flerstegsgränssnitt ”ansiktsigenkänning → Advanced Lip Sync”. Använd parametertabellen på denna sida som referens.

* **API-adress**：`POST https://api.acedata.cloud/kling/lip-sync`
* **Begärandeformat**：`application/json`
* **Svarsformat**：`application/json`
* **Debitering**：**2.45 Credits** per lyckat anrop (fast)

## Begärandehuvuden (Request Headers)

| Fält | Värde | Beskrivning |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Din API-nyckel, [hämta här](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Format för begärandetext |
| `accept` | `application/json` | Svarsformat |

## Begärandeparametrar (Request Body)

| Parameter | Typ | Obligatorisk | Standard | Beskrivning |
| - | - | - | - | - |
| `mode` | string | Ja | — | Genereringsläge. Uppräkning: `audio2video` (ljuddrivet), `text2video` (textdrivet) |
| `video_id` | string | Välj en av två | — | ID för en Kling-genererad video (t.ex. `video_id` som returneras av image2video i `/kling/videos`). **Stöder endast 5s/10s-videor genererade inom 30 dagar**. Välj en av `video_id` och `video_url`; de kan inte skickas samtidigt |
| `video_url` | string | Välj en av två | — | Offentligt tillgänglig videolänk. Begränsningar: `.mp4`/`.mov`, ≤100MB, längd 2–10s, endast 720p/1080p, sidlängd 720–1920px. Välj en av `video_id` och `video_url` |
| `audio_url` | string | Villkorligt | — | Nedladdnings-URL för det drivande ljudet, krävs vid `audio2video` + `audio_type=url`. Format `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | Nej | `url` | Överföringssätt för ljud. Uppräkning: `url`, `file` (gäller vid `audio2video`) |
| `audio_file` | string | Villkorligt | — | Base64 för ljudfilen, krävs vid `audio_type=file`. Samma format som ovan, ≤5MB |
| `text` | string | Villkorligt | — | Texten som ska läsas upp, krävs vid `text2video`, **högst 120 tecken** |
| `voice_id` | string | Villkorligt | — | Röst-ID, krävs vid `text2video` |
| `voice_language` | string | Nej | `zh` | Röstspråk. Uppräkning: `zh`, `en` (gäller vid `text2video`) |
| `voice_speed` | float | Nej | `1.0` | Talhastighet, intervall `0.8`–`2.0`, med en decimals precision (gäller vid `text2video`) |
| `callback_url` | string | Nej | — | Återanropsadress. Om detta skickas eller `async=true` används är det **asynkront läge**: `task_id` returneras omedelbart och återanrop sker när resultatet har genererats |
| `async` | boolean | Nej | `false` | Om asynkront ska användas. När `true` returneras `task_id` omedelbart, använd tillsammans med polling i `/kling/tasks` eller återanrop via `callback_url` |

## Begärandeexempel

### 1）Ljuddrivet (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）Textdrivet (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
  }'
```

## Svarsexempel (synkront lyckat)

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

| Fält | Typ | Beskrivning |
| - | - | - |
| `success` | boolean | Om det lyckades |
| `task_id` | string | ID för denna uppgift (kan användas för frågor via `/kling/tasks`) |
| `video_id` | string | Kling-ID för den genererade videon (kan användas som indata för nästa `extend`/`lip-sync`) |
| `video_url` | string | URL för den genererade talande videon (har sparats på denna plattforms CDN, giltig långsiktigt) |
| `duration` | string | Videolängd (sekunder) |
| `state` | string | Uppgiftsstatus: `succeed` / `failed` |

## Asynkront läge och frågor

När `callback_url` eller `async: true` skickas, returnerar API:et **omedelbart** `task_id`; därefter kan du:

* **Polla**: `POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (gratis)
* **Återanrop**: När genereringen är klar POST:as resultatet till din `callback_url`

## Komplett flöde: Talande foto (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", ... }
```

## Felsvar

```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 | Betydelse |
| - | - | - |
| 400 | `bad_request` | Parametrar saknas eller är ogiltiga (t.ex. mode inte skickat, konflikt mellan video och audio där ett av dem ska väljas, text över 120 tecken) |
| 401 | `authorization_missing` | API-nyckel saknas eller är ogiltig |
| 403 | `forbidden` | Innehållet har blockerats av riskkontrollen |
| 429 | `too_many_requests` | Begränsning för samtidig trafik uppströms, försök igen senare |
| 500 | `api_error` | Fel uppströms eller internt |

## Obs!

* `video_id` måste vara en Kling-video som genererats inom **30 dagar** och vara **5 s eller 10 s**; använd annars `video_url` för att skicka in en video som uppfyller begränsningarna.
* Indatavideon bör ha ett **tydligt ansikte framifrån och en person**, för bästa läppsynkresultat.
* Ljud-/textlängden bör matcha videolängden (ljudet får inte vara längre än videon).
* Debitering sker vid **lyckat** resultat (2,45 Credits/gång); misslyckad parametervalidering (4xx) debiteras inte.


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