> ## 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 API guide - 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>" }`（무료）
* **콜백**：생성이 완료된 후, 결과를 귀하의 `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":"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일 이내**에 생성된 Kling 비디오여야 하며, **5초 또는 10초**여야 합니다. 그렇지 않으면 `video_url`을 사용하여 제약 조건에 맞는 비디오를 전달하세요.
* 입력 비디오는 **선명한 정면 얼굴, 1인**을 권장하며, 립싱크 효과가 가장 좋습니다.
* 오디오/텍스트 길이는 비디오 길이와 일치해야 합니다(오디오는 비디오 길이를 초과하지 않음).
* 과금은 **성공** 시 발생합니다(회당 2.45 Credits). 매개변수 검증 실패(4xx)는 과금되지 않습니다.


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