> ## 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 Sincronização Labial do Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

Faça um **vídeo Kling já existente** (5 segundos ou 10 segundos) "falar" de acordo com áudio ou texto — isto é, sincronização labial (Lip Sync). Em conjunto com o `image2video` de `/kling/videos` (para fazer uma foto se mover), é possível formar um fluxo completo de "**fotos que falam / locução de avatar digital**".

> Esta interface é um encapsulamento conveniente de etapa única fornecido pela AceDataCloud, voltado para cenários comuns orientados por áudio/texto; ela não é um espelho dos campos da interface oficial de múltiplas etapas do Kling de «reconhecimento facial → Advanced Lip Sync». Consulte a tabela de parâmetros desta página como referência.

* **Endereço da interface**: `POST https://api.acedata.cloud/kling/lip-sync`
* **Formato da solicitação**: `application/json`
* **Formato da resposta**: `application/json`
* **Cobrança**: **2.45 Credits** por cada chamada bem-sucedida (fixo)

## Cabeçalhos da solicitação (Request Headers)

| Campo | Valor | Descrição |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | Sua chave de API, [obtenha aqui](https://platform.acedata.cloud) |
| `content-type` | `application/json` | Formato do corpo da solicitação |
| `accept` | `application/json` | Formato da resposta |

## Parâmetros da solicitação (Request Body)

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `mode` | string | Sim | — | Modo de geração. Enumeração: `audio2video` (orientado por áudio), `text2video` (orientado por texto) |
| `video_id` | string | Escolha um de dois | — | ID do vídeo gerado pelo Kling (como o `video_id` retornado pelo image2video de `/kling/videos`). **Compatível apenas com vídeos de 5s/10s gerados nos últimos 30 dias**. Escolha um entre `video_id` e `video_url`; não podem ser enviados simultaneamente |
| `video_url` | string | Escolha um de dois | — | Link de vídeo acessível publicamente. Restrições: `.mp4`/`.mov`, ≤100MB, duração de 2–10s, apenas 720p/1080p, lados de 720–1920px. Escolha um entre este e `video_id` |
| `audio_url` | string | Condicional | — | URL de download do áudio condutor, obrigatório quando `audio2video` + `audio_type=url`. Formatos `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB |
| `audio_type` | string | Não | `url` | Método de transmissão do áudio. Enumeração: `url`, `file` (válido em `audio2video`) |
| `audio_file` | string | Condicional | — | Base64 do arquivo de áudio, obrigatório quando `audio_type=file`. Mesmo formato acima, ≤5MB |
| `text` | string | Condicional | — | Texto a ser lido, obrigatório em `text2video`, **máximo de 120 caracteres** |
| `voice_id` | string | Condicional | — | ID da voz, obrigatório em `text2video` |
| `voice_language` | string | Não | `zh` | Idioma da voz. Enumeração: `zh`, `en` (válido em `text2video`) |
| `voice_speed` | float | Não | `1.0` | Velocidade de fala, intervalo de `0.8`–`2.0`, com precisão de uma casa decimal (válido em `text2video`) |
| `callback_url` | string | Não | — | Endereço de callback. Ao enviar este item ou `async=true`, entra no **modo assíncrono**: retorna imediatamente `task_id`, e faz callback após a geração do resultado |
| `async` | boolean | Não | `false` | Se é assíncrono. Quando `true`, retorna imediatamente `task_id`, em conjunto com consulta por polling em `/kling/tasks` ou callback em `callback_url` |

## Exemplos de solicitação

### 1）Orientado por áudio（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）Orientado 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
  }'
```

## Exemplo de resposta (sucesso 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 | Descrição |
| - | - | - |
| `success` | boolean | Se foi bem-sucedido |
| `task_id` | string | ID desta tarefa (pode ser usado para consultar em `/kling/tasks`) |
| `video_id` | string | ID Kling do vídeo gerado (pode ser usado como entrada do próximo `extend`/`lip-sync`) |
| `video_url` | string | URL do vídeo falante gerado (já transferido para o CDN desta plataforma, válido por longo prazo) |
| `duration` | string | Duração do vídeo (segundos) |
| `state` | string | Status da tarefa: `succeed` / `failed` |

## Modo assíncrono e consulta

Ao enviar `callback_url` ou `async: true`, a interface **retorna imediatamente** `task_id`; depois é possível:

* **Polling**: `POST /kling/tasks`, body `{ "action": "retrieve", "id": "<task_id>" }` (gratuito)
* **Callback**: após a conclusão da geração, o resultado é enviado via POST para o seu `callback_url`

## Fluxo completo: fotos que falam（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", ... }
```

## Resposta de erro

```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 ausentes ou inválidos (por exemplo, mode não informado, conflito entre video e audio, text excede 120 caracteres) |
| 401 | `authorization_missing` | Chave de API ausente ou inválida |
| 403 | `forbidden` | Conteúdo bloqueado pelo controle de risco |
| 429 | `too_many_requests` | Limite de concorrência do upstream, tente novamente mais tarde |
| 500 | `api_error` | Erro do upstream ou interno |

## Observações

* `video_id` deve ser um vídeo Kling gerado nos **últimos 30 dias** e ter **5s ou 10s**; caso contrário, use `video_url` para enviar um vídeo que atenda às restrições.
* Recomenda-se que o vídeo de entrada tenha um **rosto frontal nítido, de uma única pessoa**, para obter o melhor efeito de sincronização labial.
* A duração do áudio/texto deve corresponder à duração do vídeo (o áudio não deve exceder a duração do vídeo).
* A cobrança ocorre em caso de **sucesso** (2,45 Credits/vez); falhas na validação de parâmetros (4xx) não são cobradas.


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