> ## 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（Kling Lip Sync）

> Kling video generation 整合指南 - Ace Data Cloud

讓一段**已有的可靈影片**（5 秒或 10 秒）按音訊或文字「開口說話」——即對口型（Lip Sync）。搭配 `/kling/videos` 的 `image2video`（讓照片動起來），即可串成完整的「**會說話的照片 / 數位人口播**」流程。

> 本介面是 AceDataCloud 提供的單步便利封裝，面向常見的音訊／文字驅動場景；它不是 Kling 官方「人臉辨識 → Advanced Lip Sync」多步介面的欄位鏡像。請以本頁參數表為準。

* **介面位址**：`POST https://api.acedata.cloud/kling/lip-sync`
* **請求格式**：`application/json`
* **回應格式**：`application/json`
* **計費**：每次成功呼叫 **2.45 Credits**（固定）

## 請求標頭（Request Headers）

| 欄位 | 值 | 說明 |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | 你的 API 金鑰，[取得位址](https://platform.acedata.cloud) |
| `content-type` | `application/json` | 請求本文格式 |
| `accept` | `application/json` | 回應格式 |

## 請求參數（Request Body）

| 參數 | 類型 | 必填 | 預設 | 說明 |
| - | - | - | - | - |
| `mode` | string | 是 | — | 生成模式。列舉：`audio2video`（音訊驅動）、`text2video`（文字驅動） |
| `video_id` | string | 二選一 | — | 可靈生成影片的 ID（如 `/kling/videos` 的 image2video 回傳的 `video_id`）。**僅支援 30 天內生成的 5s/10s 影片**。`video_id` 與 `video_url` 二選一，不可同時傳入 |
| `video_url` | string | 二選一 | — | 公網可存取的影片連結。限制：`.mp4`/`.mov`，≤100MB，時長 2–10s，僅 720p/1080p，邊長 720–1920px。與 `video_id` 二選一 |
| `audio_url` | string | 條件 | — | 驅動音訊的下載 URL，`audio2video` + `audio_type=url` 時必填。格式 `.mp3`/`.wav`/`.m4a`/`.aac`，≤5MB |
| `audio_type` | string | 否 | `url` | 音訊傳輸方式。列舉：`url`、`file`（`audio2video` 時生效） |
| `audio_file` | string | 條件 | — | 音訊檔案的 Base64，`audio_type=file` 時必填。格式同上，≤5MB |
| `text` | string | 條件 | — | 要朗讀的文字，`text2video` 時必填，**最多 120 字** |
| `voice_id` | string | 條件 | — | 音色 ID，`text2video` 時必填 |
| `voice_language` | string | 否 | `zh` | 音色語言。列舉：`zh`、`en`（`text2video` 時生效） |
| `voice_speed` | float | 否 | `1.0` | 語速，範圍 `0.8`–`2.0`，精確到一位小數（`text2video` 時生效） |
| `callback_url` | string | 否 | — | 回呼位址。傳入此項或 `async=true` 則**非同步模式**：立即回傳 `task_id`，結果生成後回呼 |
| `async` | boolean | 否 | `false` | 是否非同步。`true` 時立即回傳 `task_id`，搭配 `/kling/tasks` 輪詢或 `callback_url` 回呼 |

## 請求範例

### 1）音訊驅動（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）文字驅動（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
  }'
```

## 回應範例（同步成功）

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

| 欄位 | 類型 | 說明 |
| - | - | - |
| `success` | boolean | 是否成功 |
| `task_id` | string | 本次任務 ID（可用於 `/kling/tasks` 查詢） |
| `video_id` | string | 生成影片的可靈 ID（可作為下一次 `extend`/`lip-sync` 的輸入） |
| `video_url` | string | 生成的說話影片 URL（已轉存至本平台 CDN，長期有效） |
| `duration` | string | 影片時長（秒） |
| `state` | string | 任務狀態：`succeed` / `failed` |

## 非同步模式與查詢

傳入 `callback_url` 或 `async: true` 時，介面**立即回傳** `task_id`；之後可：

* **輪詢**：`POST /kling/tasks`，body `{ "action": "retrieve", "id": "<task_id>" }`（免費）
* **回呼**：生成完成後，結果 POST 到你的 `callback_url`

## 完整流程：會說話的照片（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", ... }
```

## 錯誤回應

```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 | 含義 |
| - | - | - |
| 400 | `bad_request` | 參數缺失或不合法（如未傳 mode、video 與 audio 二選一衝突、text 超過 120 字） |
| 401 | `authorization_missing` | 缺少或無效的 API 金鑰 |
| 403 | `forbidden` | 內容被風控攔截 |
| 429 | `too_many_requests` | 上游並發限制，請稍後重試 |
| 500 | `api_error` | 上游或內部錯誤 |

## 注意事項

* `video_id` 必須是**30 天內**生成的可靈影片，且為 **5s 或 10s**；否則請用 `video_url` 傳入符合約束的影片。
* 輸入影片建議**清晰正臉、單人**，口型效果最佳。
* 音訊/文字時長應與影片時長匹配（音訊不超過影片長度）。
* 計費在**成功**時發生（2.45 Credits/次）；參數驗證失敗（4xx）不計費。


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