> ## 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 di sincronizzazione labiale di Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Fai in modo che un **video Kling esistente** (di 5 o 10 secondi) "parli" seguendo l'audio o il testo, ovvero esegua la sincronizzazione labiale (Lip Sync). In combinazione con `image2video` di `/kling/videos` (per animare una foto), puoi creare un flusso completo di "**foto parlante / presentazione di avatar digitale**".

> Questa API è un comodo wrapper a passaggio singolo fornito da AceDataCloud, pensato per scenari comuni guidati da audio/testo; non è una replica dei campi dell'API ufficiale Kling multi-passaggio «riconoscimento facciale → Advanced Lip Sync». Fai riferimento alla tabella dei parametri in questa pagina.

* **Endpoint API**: `POST https://api.acedata.cloud/kling/lip-sync`
* **Formato della richiesta**: `application/json`
* **Formato della risposta**: `application/json`
* **Fatturazione**: **2.45 Credits** per ogni chiamata riuscita (fisso)

## Intestazioni della richiesta (Request Headers)

| Campo | Valore | Descrizione |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | La tua chiave API, [ottienila qui](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Formato del corpo della richiesta |
| `accept` | `application/json` | Formato della risposta |

## Parametri della richiesta (Request Body)

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
| - | - | - | - | - |
| `mode` | string | Sì | — | Modalità di generazione. Enumerazione: `audio2video` (guidata da audio), `text2video` (guidata da testo) |
| `video_id` | string | Uno dei due | — | ID del video generato da Kling (ad esempio il `video_id` restituito da image2video di `/kling/videos`). **Sono supportati solo video di 5s/10s generati entro 30 giorni**. Scegli uno tra `video_id` e `video_url`; non possono essere passati contemporaneamente |
| `video_url` | string | Uno dei due | — | Link video accessibile pubblicamente. Vincoli: `.mp4`/`.mov`, ≤100MB, durata 2–10s, solo 720p/1080p, lato 720–1920px. Scegli uno tra questo e `video_id` |
| `audio_url` | string | Condizionale | — | URL di download dell'audio di guida, obbligatorio quando `audio2video` + `audio_type=url`. Formati `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | No | `url` | Modalità di trasmissione audio. Enumerazione: `url`, `file` (effettivo con `audio2video`) |
| `audio_file` | string | Condizionale | — | Base64 del file audio, obbligatorio quando `audio_type=file`. Formato come sopra, ≤5MB |
| `text` | string | Condizionale | — | Testo da leggere, obbligatorio con `text2video`, **massimo 120 caratteri** |
| `voice_id` | string | Condizionale | — | ID del timbro vocale, obbligatorio con `text2video` |
| `voice_language` | string | No | `zh` | Lingua del timbro vocale. Enumerazione: `zh`, `en` (effettivo con `text2video`) |
| `voice_speed` | float | No | `1.0` | Velocità del parlato, intervallo `0.8`–`2.0`, precisa a una cifra decimale (effettivo con `text2video`) |
| `callback_url` | string | No | — | Indirizzo di callback. Passando questo parametro o `async=true`, viene attivata la **modalità asincrona**: restituisce immediatamente `task_id`, con callback dopo la generazione del risultato |
| `async` | boolean | No | `false` | Se eseguire in modo asincrono. Quando è `true`, restituisce immediatamente `task_id`, da usare con il polling di `/kling/tasks` o il callback di `callback_url` |

## Esempi di richiesta

### 1）Guidata da audio（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）Guidata da testo（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
  }'
```

## Esempio di risposta (successo sincrono)

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

| Campo | Tipo | Descrizione |
| - | - | - |
| `success` | boolean | Se l'operazione è riuscita |
| `task_id` | string | ID di questa attività (può essere usato per la query tramite `/kling/tasks`) |
| `video_id` | string | ID Kling del video generato (può essere usato come input per il successivo `extend`/`lip-sync`) |
| `video_url` | string | URL del video parlante generato (salvato nella CDN di questa piattaforma, valido a lungo termine) |
| `duration` | string | Durata del video (secondi) |
| `state` | string | Stato dell'attività: `succeed` / `failed` |

## Modalità asincrona e query

Quando viene passato `callback_url` o `async: true`, l'API restituisce **immediatamente** `task_id`; successivamente puoi:

* **Polling**: `POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (gratuito)
* **Callback**: al termine della generazione, il risultato viene inviato tramite POST al tuo `callback_url`

## Flusso completo: foto parlante (image2video → lip-sync)

```bash theme={null}
# Passaggio 1: anima la foto, ottieni 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":"guarda la fotocamera, naturale","duration":5,"mode":"pro"}'
# → { "video_id": "895055164389466178", ... }

# Passaggio 2: sincronizza le labbra con l'audio
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", ... }
```

## Risposta di errore

```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 | Significato |
| - | - | - |
| 400 | `bad_request` | Parametri mancanti o non validi (ad esempio mode non inviato, conflitto tra video e audio in alternativa, text oltre 120 caratteri) |
| 401 | `authorization_missing` | Chiave API mancante o non valida |
| 403 | `forbidden` | Contenuto bloccato dal controllo del rischio |
| 429 | `too_many_requests` | Limite di concorrenza a monte, riprovare più tardi |
| 500 | `api_error` | Errore a monte o interno |

## Note

* `video_id` deve essere un video Kling generato entro **30 giorni** e deve essere di **5s o 10s**; altrimenti, usare `video_url` per passare un video che soddisfi i vincoli.
* Si consiglia che il video di input mostri un **volto frontale nitido e una sola persona**, per il miglior effetto di sincronizzazione labiale.
* La durata dell'audio/testo deve corrispondere alla durata del video (l'audio non deve superare la lunghezza del video).
* La fatturazione avviene in caso di **successo** (2,45 Credits/volta); gli errori di convalida dei parametri (4xx) non vengono addebitati.


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