Kling Lip Sync API

Drive an existing Kling video (5s or 10s) with audio or text so the character speaks in sync (lip sync). Pair it with /kling/videos image2video (which animates a still photo) to build a complete talking-photo / digital-human narration pipeline.

Endpoint: POST https://api.acedata.cloud/kling/lip-sync
Request format: application/json
Response format: application/json
Pricing: 2.45 Credits per successful call (flat)

¶ Request Headers

Field	Value	Description
`authorization`	`Bearer ${API_KEY}`	Your API key, get it here
`content-type`	`application/json`	Request body format
`accept`	`application/json`	Response format

¶ Request Body

Field	Type	Required	Default	Description
`mode`	string	yes	—	Generation mode. Enum: `audio2video`, `text2video`
`video_id`	string	one-of	—	ID of a Kling-generated video (e.g. the `video_id` returned by `/kling/videos` image2video). Only 5s/10s videos generated within the last 30 days. Provide `video_id` OR `video_url`, not both
`video_url`	string	one-of	—	Public URL of a video. Constraints: `.mp4`/`.mov`, ≤100MB, 2–10s, 720p/1080p only, dimensions 720–1920px. Provide `video_id` OR `video_url`
`audio_url`	string	conditional	—	Download URL of the driving audio. Required when `mode=audio2video` and `audio_type=url`. Formats `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB
`audio_type`	string	no	`url`	How audio is supplied. Enum: `url`, `file` (used when `audio2video`)
`audio_file`	string	conditional	—	Base64 of the audio file. Required when `audio_type=file`. Same formats, ≤5MB
`text`	string	conditional	—	Text to speak. Required when `mode=text2video`, max 120 chars
`voice_id`	string	conditional	—	Voice ID. Required when `mode=text2video`
`voice_language`	string	no	`zh`	Voice language. Enum: `zh`, `en` (used when `text2video`)
`voice_speed`	float	no	`1.0`	Speech rate, range `0.8`–`2.0`, one decimal place (used when `text2video`)
`callback_url`	string	no	—	Callback URL. Providing this (or `async=true`) switches to async mode: returns a `task_id` immediately and calls back when done
`async`	boolean	no	`false`	Async mode. When `true`, returns `task_id` immediately; poll via `/kling/tasks` or receive `callback_url`

¶ Request Examples

¶ 1) Audio-driven (audio2video)

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) Text-driven (text2video)

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": "Hi, long time no see. I am doing well, take care of yourself.",
    "voice_id": "genshin_vindi2",
    "voice_language": "en",
    "voice_speed": 1.0
  }'

¶ Response (synchronous success)

{
  "success": true,
  "task_id": "07a3ec65-9f7e-4a09-b7b7-282684082527",
  "video_id": "895055968777281546",
  "video_url": "https://platform2.cdn.acedata.cloud/kling/07a3ec65-9f7e-4a09-b7b7-282684082527.mp4",
  "duration": "4.966",
  "state": "succeed"
}

Field	Type	Description
`success`	boolean	Whether the call succeeded
`task_id`	string	Task ID (use with `/kling/tasks` to query)
`video_id`	string	Kling ID of the generated video (reusable for the next `extend`/`lip-sync`)
`video_url`	string	URL of the talking video (re-hosted on our CDN, long-lived)
`duration`	string	Video duration in seconds
`state`	string	Task status: `succeed` / `failed`

¶ Async mode & querying

When callback_url or async: true is provided, the endpoint returns immediately with a task_id. Then:

Poll: POST /kling/tasks with body { "action": "retrieve", "id": "<task_id>" } (free)
Callback: the result is POSTed to your callback_url when ready

¶ Full pipeline: talking photo (image2video → lip-sync)

# Step 1: animate the photo, get a 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", ... }

# Step 2: lip-sync it with 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://your.cdn/voice.mp3"}'
# → { "video_url": "https://platform2.cdn.acedata.cloud/kling/....mp4", ... }

¶ Error response

{
  "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	Meaning
400	`bad_request`	Missing/invalid params (e.g. no mode, video/audio conflict, text over 120 chars)
401	`authorization_missing`	Missing or invalid API key
403	`forbidden`	Blocked by content moderation
429	`too_many_requests`	Upstream concurrency limit, retry later
500	`api_error`	Upstream or internal error

¶ Notes

video_id must be a Kling video generated within 30 days and 5s or 10s; otherwise pass a constraint-compliant video via video_url.
A clear, frontal, single-person video gives the best lip-sync.
Audio/text length should match the video length (audio no longer than the video).
Billing happens on success (2.45 Credits/call); validation failures (4xx) are not billed.