> ## 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 Videos Generation API Integration Instructions > Kling video generation integration guide - Ace Data Cloud This article will introduce the integration instructions for the Kling Videos Generation API, which can generate official Kling videos by inputting custom parameters. ## Application Process To use the Kling Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page, inviting you to register and log in. After completing this, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > πŸ“˜ Complete Documentation: [Kling Videos Generation API β†’](https://platform.acedata.cloud/documents/kling-videos) ## Basic Usage First, understand the basic usage, which involves inputting the prompt `prompt`, the generation action `action`, the first frame reference image `start_image_url`, and the model `model` to obtain the processed result. You first need to simply pass a field `action` with the value `text2video`, which mainly includes three actions: text-to-video (`text2video`), image-to-video (`image2video`), and video extension (`extend`). Then, we also need to input the model `model`, which currently includes `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, and `kling-o1`, with specific details as follows:

Here we can see that we have set the Request Headers, including: * `accept`: the format of the response result you want to receive, filled in as `application/json`, which means JSON format. * `authorization`: the key to call the API, which can be directly selected after application. Additionally, we have set the Request Body, including: * `model`: the model for generating the video, mainly including `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, and `kling-o1`. * `mode`: the mode for generating the video, with optional values of standard mode `std`, fast mode `pro`, and native 4K mode `4k`. The `4k` mode only supports `kling-v3` and `kling-v3-omni`, and is incompatible with `camera_control` (camera movement control). * `action`: the action for this video generation task, mainly including three actions: text-to-video (`text2video`), image-to-video (`image2video`), and video extension (`extend`). * `start_image_url`: when selecting the image-to-video action `image2video`, the first frame reference image link must be uploaded. * `end_image_url`: optional for image-to-video, specifies the last frame. * `duration`: video duration, in seconds. `kling-v3` and `kling-v3-omni` support integer durations of 3-15 seconds; `kling-o1` only supports 5 seconds; other models support 5 or 10 seconds. * `generate_audio`: whether to generate audio synchronously, optional, boolean value. Supports `kling-v3`, `kling-v3-omni`, and `kling-v2-6` (only in pro mode). Default is `false`. * `aspect_ratio`: video aspect ratio, optional, supports `16:9`, `9:16`, `1:1`, default is `16:9`. * `cfg_scale`: correlation strength, range \[0,1], larger values are more aligned with the prompt. * `camera_control`: optional, parameters to control camera movement, supports type/simple presets and configurations such as horizontal, vertical, pan, tilt, roll, zoom, etc. * `negative_prompt`: optional, reverse prompt words that you do not want to appear, up to 200 characters. * `image_list`: Omni reference image list, applicable to models `kling-o1` and `kling-v3-omni`, usage is described in the section "Omni All-Purpose Reference" below. * `video_list`: Omni reference video list (supports video editing), applicable to models `kling-o1` and `kling-v3-omni`, usage is described in the section "Omni All-Purpose Reference" below. * `prompt`: prompt words. * `callback_url`: the URL to receive callback results. * `async`: optional, when set to `true`, the interface immediately returns `task_id`, no need to provide `callback_url`, and then the result can be polled through the corresponding task query interface. After selection, you can see that the corresponding code is generated on the right side, as shown in the figure:

Click the "Try" button to test, as shown in the above figure, we obtained the following result: ```json theme={null} { "success": true, "video_id": "900798310464749610", "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.mp4", "duration": "5.041", "state": "succeed", "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5" } ``` The returned result contains multiple fields, described as follows: * `success`: the status of the video generation task at this time. * `task_id`: the ID of the video generation task at this time. * `video_id`: the video ID of the video generation task at this time. * `video_url`: the video link of the video generation task at this time. * `duration`: the duration of the video generation task at this time. * `state`: the status of the video generation task at this time. We can see that we have obtained satisfactory video information, and we only need to access the generated Kling video using the video link address in the `data` result. Additionally, if you want to generate the corresponding integration code, you can directly copy it, for example, the CURL code is as follows: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v3", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }' ``` ## Model Capability Matrix Different models have varying support for parameters. The following matrix is organized from the [Kling official video models documentation](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels). Please verify that the current `model` / `mode` / `duration` combination supports the features you need before calling, otherwise, upstream will return errors such as `model/mode/duration(...) is not supported with image_tail`. | Model | Mode | `end_image_url` (First and Last Frame) | `generate_audio` (Accompanying Audio) | `camera_control` (Camera Movement) | Remarks | | ------------------- | -------------- | -------------------------------------- | ------------------------------------- | ---------------------------------- | ----------------------------------------------------------- | | `kling-v1` | std / pro | βœ… Only `duration=5` | ❌ | βœ… Only `duration=5` | `extend` does not support `negative_prompt` and `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | Multi-image video, `extend` available in all modes | | `kling-v1-6` | pro | βœ… | ❌ | ❌ | | | `kling-v2-master` | β€” | ❌ | ❌ | ❌ | Single mode, only `duration=5/10` | | `kling-v2-1-master` | β€” | ❌ | ❌ | ❌ | Single mode, only `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | βœ… | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | βœ… | βœ… | ❌ | The only non-v3 model that supports accompanying audio | | `kling-v3` | std / pro | βœ… | βœ… | βœ… | `duration` range 3–15 seconds | | `kling-v3` | 4k | βœ… | βœ… | ❌ | 4K mode is incompatible with camera movement | | `kling-v3-omni` | std / pro / 4k | βœ… | βœ… | ❌ | | | `kling-o1` | std / pro | βœ… | ❌ | ❌ | Only supports `duration=5` | Notes: * `mode=4k` is only supported by `kling-v3` and `kling-v3-omni`; it is mutually exclusive with `camera_control`. * `end_image_url` can only be used with `start_image_url` when `action=image2video`. Providing only `end_image_url` (without `start_image_url`) will be rejected. * `kling-v3` / `kling-v3-omni` accept any integer `duration` from 3 to 15 seconds; `kling-o1` only accepts 5; other models only accept 5 or 10. * `generate_audio` defaults to `false`. Only `kling-v3`, `kling-v3-omni`, and `kling-v2-6` (pro mode) support it. ## Video Extension Functionality If you want to continue generating a Kling video that has already been created, you can set the parameter `action` to `extend` and input the ID of the video you want to continue generating. The video ID can be obtained based on basic usage, as shown in the image below:

At this point, you can see the video ID is: ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > Note that the `video_id` here is the ID of the generated video. If you do not know how to generate a video, you can refer to the basic usage mentioned above. Next, we must fill in the prompt for the next step to customize the generated video, specifying the following content: * `model`: The model for generating the video, mainly `kling-v1`, `kling-v1-5`, and `kling-v1-6`. * `mode`: The mode for generating the video, with optional values of standard mode `std`, high-speed mode `pro`, and native 4K mode `4k` (only supported by `kling-v3` and `kling-v3-omni`, incompatible with camera control). * `duration`: The duration of this video generation task, mainly including 5s and 10s. * `start_image_url`: When selecting the image-to-video action `image2video`, the first frame reference image link must be uploaded. * `prompt`: The prompt. An example of filling in is as follows:

After filling it out, the code is automatically generated as follows:

Corresponding Python code: ```python theme={null} import requests url = "https://api.acedata.cloud/kling/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "extend", "model": "kling-v1", "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Clicking run, you can find that you will get a result as follows: ```json theme={null} { "success": true, "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4", "duration": "9.6", "state": "succeed", "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23" } ``` It can be seen that the result content is consistent with the above, thus achieving the video extension functionality. ## Omni Universal Reference (Video Editing / Reference Video / Multi-Image Reference) `kling-o1` and `kling-v3-omni` are two independent models, both supporting "universal reference" capabilities. Based on text-to-video (`action=text2video`), additional reference images or videos can be provided to achieve **multi-image reference, reference video, and direct editing of existing videos**. **Core Agreement**: Reference materials must be referenced in the `prompt` in the form of `<<>>`, `<<>>` (with numbering starting from 1) corresponding to the positions in `image_list` / `video_list`, for the model to apply these references. If materials are provided without being referenced in the prompt, they will be ignored. > Safety Note: The current API does not open `element_list`. The upstream ID of the Kling Element Library belongs to the provider account namespace. Before providing tenant isolation through the Element Management API, customers should use `image_list` to pass in the main reference images. Omni requests do not support `negative_prompt`, `cfg_scale`, or `camera_control`, and cannot use `mode=4k`. When including reference videos, `generate_audio` must be `false`. ### Reference Video and Video Editing (`video_list`) `video_list` is used to pass in reference videos, which is the most commonly used scenario for this capability. The fields of the array elements are as follows: * `video_url`: Reference video link, cannot be empty. Requirements: format MP4/MOV; resolution 720px–2160px; duration 3–10 seconds; frame rate 24–60fps; file size ≀200MB; up to 1 video. * `refer_type`: Reference type, optional `base` (default, **the basic video to be edited**, i.e., "directly edit the video", can add/delete/modify elements, change composition, change style, change color, change weather, etc.) or `feature` (**feature reference**, reference its style / camera movement / continuation of the next shot). * `keep_original_sound`: Whether to keep the original video audio, optional `yes` (keep) or `no` (remove). > Note: When a reference video exists, `generate_audio` must be `false`. Videos with `refer_type=base` cannot specify the first frame / last frame. An example of CURL for editing an existing video (changing the video to an anime style) is as follows: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Change <<>> to a movie-level anime style, keeping the original motion and composition", "video_list": [ { "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4", "refer_type": "base", "keep_original_sound": "no" } ] }' ``` ### Multi-Image Reference (`image_list`) `image_list` is used to pass in reference images (elements / scenes / styles, etc.), the fields of the array elements are as follows: * `image_url`: Reference image link, cannot be empty. Requirements: format .jpg/.jpeg/.png; file size ≀10MB; shortest side β‰₯300px; aspect ratio 1:2.5 \~ 2.5:1. * `type`: Optional. If not provided, treated as a pure reference image; if `first_frame` / `end_frame` is provided, treated as the first frame / last frame (equivalent to `start_image_url` / `end_image_url`). When using, it should be referenced in `prompt` as `<<>>`, `<<>>`. Quantity limit: if there is no reference video, reference images ≀ 7; if there is a reference video, reference images ≀ 4. If only the first / last frame is provided, `start_image_url` / `end_image_url` can also be used directly, but the last frame must be used together with the first frame. > Note: If both `start_image_url` / `end_image_url` and `image_list` are provided, the first / last frame will be placed before `image_list`, which may affect the corresponding relationship of `<<>>`. It is recommended to choose one: if first / last frames are needed, specify directly in `image_list` using `type`, do not mix with `start_image_url` / `end_image_url`. An example of CURL for generating a video with multi-image reference: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Let the character in <<>> stand in the scene of <<>>, cinematic lighting", "image_list": [ { "image_url": "https://cdn.acedata.cloud/subject.png" }, { "image_url": "https://cdn.acedata.cloud/scene.png" } ] }' ``` ## Asynchronous Callback Due to the relatively long generation time of the Kling Videos Generation API, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the result of the generated video will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let’s understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, a public Webhook sample site [https://webhook.site/](https://webhook.site/) is used, and opening this site will provide a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/tbcnai.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`. Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the image:

Clicking run, you can find that an immediate result is obtained, as follows: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` After a moment, we can observe the result of the generated video at `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, as shown in the image: ![](https://cdn.acedata.cloud/zv5u2q.png) The content is as follows: ```json theme={null} { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` It can be seen that the result contains a `task_id` field, and the other fields are similar to those mentioned above, allowing the task to be associated through this field. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: * `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. * `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. * `401 invalid_token`: Unauthorized, invalid or missing authorization token. * `429 too_many_requests`: Too many requests, you have exceeded the rate limit. * `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Kling Videos Generation API to generate videos by inputting prompt words and a reference image for the first frame. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.