> ## 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 de sincronización labial de Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Haz que un **video existente de Kling** (de 5 o 10 segundos) "hable" según audio o texto — es decir, sincronización labial (Lip Sync). Combinado con `image2video` de `/kling/videos` (para hacer que una foto se mueva), puede formar un flujo completo de "**fotos parlantes / locución de avatar digital**".

> Esta interfaz es un encapsulado práctico de un solo paso proporcionado por AceDataCloud, orientado a escenarios comunes impulsados por audio/texto; no es un reflejo de los campos de la interfaz oficial de múltiples pasos de Kling «reconocimiento facial → Advanced Lip Sync». Consulta la tabla de parámetros de esta página.

* **Dirección de la interfaz**: `POST https://api.acedata.cloud/kling/lip-sync`
* **Formato de solicitud**: `application/json`
* **Formato de respuesta**: `application/json`
* **Facturación**: **2.45 Credits** por cada llamada exitosa (fijo)

## Encabezados de solicitud (Request Headers)

| Campo | Valor | Descripción |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Tu clave de API, [obtener aquí](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Formato del cuerpo de la solicitud |
| `accept` | `application/json` | Formato de respuesta |

## Parámetros de solicitud (Request Body)

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| - | - | - | - | - |
| `mode` | string | Sí | — | Modo de generación. Enumeración: `audio2video` (impulsado por audio), `text2video` (impulsado por texto) |
| `video_id` | string | Uno de dos | — | ID del video generado por Kling (como el `video_id` devuelto por image2video de `/kling/videos`). **Solo admite videos de 5s/10s generados dentro de los últimos 30 días**. Elige uno entre `video_id` y `video_url`; no se pueden enviar al mismo tiempo |
| `video_url` | string | Uno de dos | — | Enlace de video accesible públicamente. Restricciones: `.mp4`/`.mov`, ≤100MB, duración 2–10s, solo 720p/1080p, lado de 720–1920px. Elige uno entre este y `video_id` |
| `audio_url` | string | Condicional | — | URL de descarga del audio controlador, obligatoria cuando `audio2video` + `audio_type=url`. Formatos `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | No | `url` | Método de transmisión de audio. Enumeración: `url`, `file` (efectivo cuando se usa `audio2video`) |
| `audio_file` | string | Condicional | — | Base64 del archivo de audio, obligatorio cuando `audio_type=file`. Mismos formatos que arriba, ≤5MB |
| `text` | string | Condicional | — | Texto que se leerá, obligatorio cuando se usa `text2video`, **máximo 120 caracteres** |
| `voice_id` | string | Condicional | — | ID de voz, obligatorio cuando se usa `text2video` |
| `voice_language` | string | No | `zh` | Idioma de voz. Enumeración: `zh`, `en` (efectivo cuando se usa `text2video`) |
| `voice_speed` | float | No | `1.0` | Velocidad de habla, rango `0.8`–`2.0`, con precisión de un decimal (efectivo cuando se usa `text2video`) |
| `callback_url` | string | No | — | Dirección de devolución de llamada. Si se proporciona este elemento o `async=true`, se utiliza el **modo asíncrono**: devuelve inmediatamente `task_id`, y realiza la devolución de llamada después de generar el resultado |
| `async` | boolean | No | `false` | Si es asíncrono. Cuando es `true`, devuelve inmediatamente `task_id`, en combinación con el sondeo de `/kling/tasks` o la devolución de llamada de `callback_url` |

## Ejemplos de solicitud

### 1）Impulsado por 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）Impulsado por texto (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
  }'
```

## Ejemplo de respuesta (éxito síncrono)

```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 | Descripción |
| - | - | - |
| `success` | boolean | Si tuvo éxito |
| `task_id` | string | ID de esta tarea (se puede usar para consultar `/kling/tasks`) |
| `video_id` | string | ID de Kling del video generado (puede utilizarse como entrada para el siguiente `extend`/`lip-sync`) |
| `video_url` | string | URL del video hablado generado (ya transferido al CDN de esta plataforma, válido a largo plazo) |
| `duration` | string | Duración del video (segundos) |
| `state` | string | Estado de la tarea: `succeed` / `failed` |

## Modo asíncrono y consulta

Cuando se proporciona `callback_url` o `async: true`, la interfaz **devuelve inmediatamente** `task_id`; después puedes:

* **Sondear**: `POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (gratis)
* **Devolución de llamada**: después de completar la generación, el resultado se envía mediante POST a tu `callback_url`

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

```bash theme={null}
# Paso 1: hacer que la foto se mueva, obtener 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", ... }

# Paso 2: sincronizar los labios con el 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", ... }
```

## Respuesta de error

```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 | Significado |
| - | - | - |
| 400 | `bad_request` | Parámetros faltantes o no válidos (por ejemplo, no se envió mode, conflicto entre video y audio al elegir uno de los dos, text supera los 120 caracteres) |
| 401 | `authorization_missing` | Falta una clave API o no es válida |
| 403 | `forbidden` | El contenido fue bloqueado por el control de riesgos |
| 429 | `too_many_requests` | Límite de concurrencia del proveedor, inténtelo de nuevo más tarde |
| 500 | `api_error` | Error del proveedor o interno |

## Consideraciones

* `video_id` debe ser un video de Kling generado **dentro de los últimos 30 días** y ser de **5 s o 10 s**; de lo contrario, use `video_url` para enviar un video que cumpla con las restricciones.
* Se recomienda que el video de entrada tenga un **rostro frontal claro y una sola persona** para obtener el mejor efecto de sincronización labial.
* La duración del audio/texto debe coincidir con la duración del video (el audio no debe exceder la duración del video).
* La facturación ocurre al **tener éxito** (2.45 Credits/vez); los fallos de validación de parámetros (4xx) no se cobran.


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