Kling Lip Sync API

Make an existing Kling video (5 seconds or 10 seconds) "speak" according to audio or text—i.e., lip sync. Combined with /kling/videos's image2video (to animate photos), it can form a complete "talking photo / digital avatar broadcast" process.

This interface is a single-step convenient encapsulation provided by 辰汐ai, aimed at common audio/text-driven scenarios; it is not a field mirror of the Kling official "face recognition → Advanced Lip Sync" multi-step interface. Please refer to the parameter table on this page.

Interface Address: POST https://api.acedata.cloud/kling/lip-sync
Request Format: application/json
Response Format: application/json
Billing: 2.45 Credits (fixed) for each successful call

¶ 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 Parameters

Parameter	Type	Required	Default	Description
`mode`	string	Yes	—	Generation mode. Enum: `audio2video` (audio-driven), `text2video` (text-driven)
`video_id`	string	One of two	—	The ID of the video generated by Kling (e.g., `video_id` returned by `/kling/videos`'s image2video). Only supports 5s/10s videos generated within 30 days. Either `video_id` or `video_url` must be provided, not both.
`video_url`	string	One of two	—	Publicly accessible video link. Constraints: `.mp4`/`.mov`, ≤100MB, duration 2–10s, only 720p/1080p, side length 720–1920px. Either `video_id` or `video_url` must be provided.
`audio_url`	string	Conditional	—	Download URL for the driving audio, required when `audio2video` + `audio_type=url`. Format: `.mp3`/`.wav`/`.m4a`/`.aac`, ≤5MB
`audio_type`	string	No	`url`	Audio transmission method. Enum: `url`, `file` (effective when `audio2video`)
`audio_file`	string	Conditional	—	Base64 of the audio file, required when `audio_type=file`. Same format constraints, ≤5MB
`text`	string	Conditional	—	Text to be read aloud, required when `text2video`, up to 120 characters
`voice_id`	string	Conditional	—	Voice ID, required when `text2video`
`voice_language`	string	No	`zh`	Voice language. Enum: `zh`, `en` (effective when `text2video`)
`voice_speed`	float	No	`1.0`	Speech speed, range `0.8`–`2.0`, accurate to one decimal place (effective when `text2video`)
`callback_url`	string	No	—	Callback address. If this is provided or `async=true`, it will be asynchronous mode: immediately returns `task_id`, and the result will be called back after generation
`async`	boolean	No	`false`	Whether to be asynchronous. If `true`, immediately returns `task_id`, to be polled with `/kling/tasks` or via `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": "Brother, long time no see, I am doing well, take care of yourself.",
    "voice_id": "genshin_vindi2",
    "voice_language": "zh",
    "voice_speed": 1.0
  }'

¶ Response Example (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 it was successful
`task_id`	string	This task ID (can be used to query with `/kling/tasks`)
`video_id`	string	The Kling ID of the generated video (can be used as input for the next `extend`/`lip-sync`)
`video_url`	string	The URL of the generated speaking video (stored on this platform's CDN, valid long-term)
`duration`	string	Video duration (seconds)
`state`	string	Task status: `succeed` / `failed`

¶ Asynchronous Mode and Querying

When callback_url or async: true is provided, the interface immediately returns task_id; afterwards, you can:

Poll: POST /kling/tasks, body { "action": "retrieve", "id": "<task_id>" } (free)
Callback: After generation is complete, the result will be POSTed to your callback_url

¶ Complete Process: Talking Photos (image2video → lip-sync)

# Step 1: Make the photo move, obtain 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 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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.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 or invalid parameters (e.g., missing mode, conflict between video and audio, text exceeds 120 characters)
401	`authorization_missing`	Missing or invalid API key
403	`forbidden`	Content intercepted by risk control
429	`too_many_requests`	Upstream concurrency limit, please try again later
500	`api_error`	Upstream or internal error

¶ Notes

video_id must be a valid video generated within the last 30 days, and must be 5s or 10s; otherwise, please use video_url to provide a compliant video.
Input video is recommended to be clear, frontal, and single-person, for the best lip sync effect.
Audio/text duration should match the video duration (audio should not exceed video length).
Billing occurs on success (2.45 Credits/instance); parameter validation failures (4xx) are not billed.