> ## 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リップシンク API（Kling Lip Sync）

> Kling video generation API guide - Ace Data Cloud

**既存のKling動画**（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 | いずれか一方 | — | Kling生成動画のID（例：`/kling/videos` のimage2videoが返す `video_id`）。**生成から30日以内の5秒/10秒動画のみ対応**。`video_id` と `video_url` はいずれか一方のみで、同時には渡せません |
| `video_url` | string | いずれか一方 | — | 公開アクセス可能な動画リンク。制約：`.mp4`/`.mov`、≤100MB、長さ2～10秒、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`、小数点以下1桁まで（`text2video` の場合に有効） |
| `callback_url` | string | いいえ | — | コールバックURL。この項目を渡すか `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 | 生成動画のKling 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>" }`（無料）
* **コールバック**：生成完了後、結果があなたの `callback_url` にPOSTされます

## 完全なフロー：話す写真（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":"カメラを見る、自然に","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": "video_id または video_url のいずれかが必要です" },
  "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 日以内**に生成された可霊動画であり、かつ **5 秒または 10 秒**である必要があります。それ以外の場合は、`video_url` を使用して制約に適合する動画を渡してください。
* 入力動画は**鮮明な正面顔・1 人**を推奨し、リップシンク効果が最も良くなります。
* 音声／テキストの長さは動画の長さに合わせる必要があります（音声は動画の長さを超えないこと）。
* 課金は**成功時**に発生します（2.45 Credits／回）。パラメータ検証の失敗（4xx）では課金されません。


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