kling-video

# Kling Video Generation Generate AI videos through AceDataCloud's Kuaishou Kling API. > **Setup:** See [authentication](../_shared/authentication.md) for token setup. ## Quick Start ```bash curl -X POST https://api.acedata.cloud/kling/videos \ -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"action": "text2video", "prompt": "a cat playing piano on a rooftop at sunset", "model": "kling-v3", "mode": "std", "duration": 5}' ``` > **Async:** See [async task polling](../_shared/async-tasks.md). Poll via `POST /kling/tasks` with `{"id": "..."}`. ## Models | Model | Quality | Best For | |-------|---------|----------| | `kling-v3` | Latest | Best quality, flexible 3–15s duration, optional audio generation | | `kling-v3-omni` | Latest | V3 Omni model with audio plus image/video references, flexible 3–15s duration | | `kling-v2-6` | High | High-quality output with optional audio (pro mode) | | `kling-v2-5-turbo` | High + Fast | Best speed/quality trade-off | | `kling-v2-master` | High | High-quality output | | `kling-v2-1-master` | High | Improved v2 | | `kling-v1-6` | Improved | Better quality than v1 | | `kling-v1` | Standard | Basic generation, lowest cost | | `kling-o1` | Premium | Independent O1 model with image/video references, 5s only | ## Quality Modes | Mode | Speed | Cost | Use For | |------|-------|------|---------| | `std` (Standard) | Slower | Lower | Draft/preview | | `pro` (Professional) | Faster | Higher | Final output | | `4k` (Native 4K) | — | Premium | Native 4K output — only `kling-v3` and `kling-v3-omni`; incompatible with `camera_control` | ## Workflows ### 1. Text-to-Video ```json POST /kling/videos { "action": "text2video", "prompt": "a futuristic city with flying cars", "model": "kling-v3", "mode": "std", "duration": 5, "aspect_ratio": "16:9" } ``` ### 2. Image-to-Video Animate a still image. Optionally specify an ending frame. ```json POST /kling/videos { "action": "image2video", "prompt": "the scene slowly comes alive with movement", "start_image_url": "https://example.com/scene.jpg", "end_image_url": "https://example.com/end-scene.jpg", "model": "kling-v3", "mode": "pro" } ``` ### 3. Omni References Use `kling-o1` or `kling-v3-omni` with reference images and/or one reference video. Cite each item in the prompt using its one-based token. ```json POST /kling/videos { "action": "text2video", "prompt": "turn <<<video_1>>> into hand-painted animation while preserving its motion", "model": "kling-o1", "mode": "std", "duration": 5, "video_list": [ { "video_url": "https://example.com/source.mp4", "refer_type": "base", "keep_original_sound": "no" } ] } ``` Use `refer_type: "feature"` to reference style, motion, or a neighboring shot. Use `refer_type: "base"` to edit the supplied video. A base video cannot be combined with first/end frames. ### 4. Extend Video Continue an existing video with additional seconds. ```json POST /kling/videos { "action": "extend", "video_id": "existing-video-id", "prompt": "the camera pulls back to reveal the full landscape", "model": "kling-v2-5-turbo" } ``` ### 5. Motion Control Apply precise camera/motion control from an image + reference video. ```json POST /kling/motion { "image_url": "https://example.com/subject.jpg", "video_url": "https://example.com/motion-reference.mp4", "mode": "std", "character_orientation": "image" } ``` ### 6. Lip Sync Create a lip-synced video from a source video plus either an audio track or input text. ```json POST /kling/lip-sync { "video_url": "https://example.com/source.mp4", "mode": "audio2video", "audio_url": "https://example.com/voiceover.mp3" } ``` ### 7. Talking Photo Animate a still portrait from an image plus an audio track. ```json POST /kling/talking-photo { "image_url": "https://example.com/portrait.jpg", "audio_url": "https://example.com/voiceover.mp3", "model": "kling-v2-1-master", "duration": 5, "mode": "pro" } ``` ## Parameters | Parameter | Values | Description | |-----------|--------|-------------| | `action` | `"text2video"`, `"image2video"`, `"extend"` | Generation mode | | `model` | See models table | Model to use | | `prompt` | string | Required generation or continuation instructions | | `mode` | `"std"`, `"pro"`, `"4k"` | Quality mode (`4k` only for `kling-v3` / `kling-v3-omni`, incompatible with `camera_control`) | | `duration` | O1: `5`; v3/v3-omni: `3`–`15`; others: `5`, `10` | Duration in seconds | | `start_image_url` | URL | Required first frame for `action=image2video` | | `end_image_url` | URL | Optional end frame for `image2video`; requires `start_image_url` | | `video_id` | string | Existing Kling video ID required by `action=extend` | | `generate_audio` | `true`, `false` | Generate audio with video (v3, v3-omni, v2-6 pro only) | | `aspect_ratio` | `"16:9"`, `"9:16"`, `"1:1"` | Video aspect ratio | | `cfg_scale` | 0–1 | Prompt relevance strength | | `negative_prompt` | string | What to avoid in the video | | `camera_control` | object | Camera movement parameters | | `image_list` | array | Omni reference images for `kling-o1` / `kling-v3-omni`; each item has `image_url` and optional `type` (`first_frame` / `end_frame`). Up to 7 images without a reference video, or 4 with one, including first/end frames | | `video_list` | array | One MP4/MOV Omni reference video for `kling-o1` / `kling-v3-omni` (3–10s, 720–2160px, 24–60fps, ≤200MB); item has `video_url`, `refer_type` (`feature` / `base`), and `keep_original_sound` (`yes` / `no`) | | `callback_url` | string | Async callback URL | | `mode` (`/kling/lip-sync`) | `"audio2video"`, `"text2video"` | Lip-sync mode | | `video_url` (`/kling/lip-sync`) | URL | Source video URL for lip-sync | | `video_id` (`/kling/lip-sync`) | string | Existing Kling video ID for lip-sync | | `audio_url` (`/kling/lip-sync`) | URL | Audio source URL (for `audio2video`) | | `audio_type` (`/kling/lip-sync`) | `"url"`, `"file"` | Audio input type (default `url`) | | `audio_file` (`/kling/lip-sync`) | string | Audio file payload when `audio_type=file` | | `text` (`/kling/lip-sync`) | string | Input text to synthesize speech (for `text2video`) | | `voice_id` (`/kling/lip-sync`) | string | Voice preset ID used in `text2video` | | `voice_language` (`/kling/lip-sync`) | `"zh"`, `"en"` | TTS language for `text2video` (default `zh`) | | `voice_speed` (`/kling/lip-sync`) | number | TTS speaking speed (default `1.0`) | | `mode` (`/kling/motion`) | `"std"`, `"pro"` | Motion generation quality mode | | `character_orientation` (`/kling/motion`) | `"image"`, `"video"` | Character orientation source | | `image_url` (`/kling/talking-photo`) | URL | Source portrait image | | `audio_url` (`/kling/talking-photo`) | URL | Driving audio track | | `model` (`/kling/talking-photo`) | `"kling-v1"`, `"kling-v1-6"`, `"kling-v2-master"`, `"kling-v2-1-master"`, `"kling-v2-5-turbo"`, `"kling-v2-6"` | Talking-photo model | | `duration` (`/kling/talking-photo`) | `5`, `10` | Talking-photo duration | | `mode` (`/kling/talking-photo`) | `"std"`, `"pro"` | Talking-photo quality mode | ## Gotchas - `kling-o1` supports `duration=5` only; `kling-v3` and `kling-v3-omni` support flexible `3`–`15` seconds; most other models support `5` or `10` - `mode=4k` is only available for `kling-v3` and `kling-v3-omni` and is incompatible with `camera_control` - `generate_audio` enables synchronized audio generation (supported by `kling-v3`, `kling-v3-omni`, and `kling-v2-6` in pro mode) - `end_image_url` is only for `image2video` action — it defines the last frame - Omni references are supported only by `kling-o1` and `kling-v3-omni`; cite them as `<<<image_N>>>` / `<<<video_1>>>` - Omni reference requests do not support `negative_prompt`, `cfg_scale`, `camera_control`, or `mode=4k` - With `video_list`, `generate_audio` must be `false`; a base video cannot be combined with first/end frames - `element_list` is intentionally unavailable because upstream Element IDs are not tenant-scoped; use `image_list` for subject references - Motion control (`/kling/motion`) is a separate endpoint from video generation - Lip-sync is a separate endpoint (`/kling/lip-sync`) and requires `mode`; use `audio_url` for `audio2video` or `text` + voice fields for `text2video` - Talking-photo is a separate endpoint (`/kling/talking-photo`) and requires both `image_url` and `audio_url` - `pro` mode costs roughly 2x `std` mode but generates faster with better quality - Task states use `"succeed"` (not "succeeded") — check for this value when polling - `negative_prompt` helps avoid unwanted elements (e.g., "blurry, low quality, text")