Skip to content

Kling Universal Protocol API (Text-to-Image/Image-to-Image/Motion Control/Omni)

1. Model Description

competence MaaS_KeLing_3.0_turbo MaaS_KeLing_3.0_video MaaS_KeLing_V2.6 MaaS_KeLing_V2.5_turbo MaaS_KeLing_3O_video MaaS_KeLing_O1_video MaaS_KeLing_4.0_video
Text-to-Video ✅ ✅ ✅ ✅ — — ✅
Image-to-Video ✅ ✅ ✅ ✅ — — ✅
Motion Control — ✅ ✅ — — — —
Omni Video — — — — ✅
 ✅ ✅

For the optional values of parameters for each interface and model differences, please refer to the corresponding parameter tables and supplementary descriptions in §3.

2. Billing

2.1 Platform Billing Items and Usage

Billing Item Code Dosage Calculation
credit Take billing[0].amount as the usage billing for this task

3. Details of Functional Interfaces

3.1 Text-to-Video

3.1.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/videos/text-to-video

Applicable Models (endpoints): MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo/ MaaS_KeLing_4.0_video.

3.1.2 Request Body Parameters

Parameter Name Field Type Required or not default value Description
prompt string Yes - Text prompts, which can include positive and negative descriptions. Length: MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_videomust not exceed 3072 characters, and it is recommended to be no more than 2500;MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbomust not exceed 2500 characters;MaaS_KeLing_4.0_video: ≤26000 characters for pure English, ≤11000 characters for pure non-English;(Number of English characters in the mix ÷ 26000) +(Number of non-English characters ÷ 11000) ≤ 1.
settings object No - Output configuration-related parameters, such as resolution, duration, etc.
settings.multi_shot boolean
 No true Whether to generate a multi-camera video. Only MaaS_KeLing_3.0_videosupports this feature; when set to false, a multi-camera video cannot be generated even if a prompt in multi-camera format is used. MaaS_KeLing_3.0_turbodoes not have this field, but multi-camera functionality can still be achieved via a fixed prompt format (see supplementary instructions).MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo/ MaaS_KeLing_4.0_videoNot supported (no optional values available, do not pass this field)
settings.audio
 string No off
 Specifies whether to generate a video with audio. Supported values: native, off. Only MaaS_KeLing_3.0_videoand MaaS_KeLing_V2.6support this parameter;MaaS_KeLing_3.0_turbo, MaaS_KeLing_V2.5_turbo, and MaaS_KeLing_4.0_videodo not support it (no valid values available, do not pass this field). For MaaS_KeLing_V2.6: when generating a video with audio, only 1080P resolution is supported
settings.resolution string No 720p The resolution of the generated video. Supported values: MaaS_KeLing_3.0_turbo/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbosupport 720p, 1080p;MaaS_KeLing_3.0_videosupports 720p, 1080p, 4K;MaaS_KeLing_4.0_videosupports: 720p, 1080p; default value: 1080p; 4K is not supported
settings.aspect_ratio string No 16:9 Specify the aspect ratio (width: height) of the generated video. MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turboSupported values: 16:9, 9:16, 1:1;
MaaS_KeLing_4.0_videoOptional values: 21:9, 16:9, 9:16, 1:1; default value: 16:9
settings.duration int No 5 Set the generated video duration, in seconds (s). MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_videoValid values: 3 to 15;MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turboValid values: 5, 10;
MaaS_KeLing_4.0_videoOptional values: 3,4, 5,6, 7,8, 9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30; default value 10; if not specified, the duration intent can be recognized from the Prompt
options object No - General configurations, such as callback URL, whether to include watermark, etc.
options.callback_url string No - This is the callback notification address for the result of this task. If configured, the server will actively send a notification when the task status changes. For the schema of the specific notification message, please refer to the Kling Callback Protocol.
options.external_task_id string No - Custom task ID. The passed-in ID will not overwrite the system-generated task ID, but you can use this ID to query tasks. Please note that this ID must be unique for a single user.
options.watermark_info object No - Specifies whether to generate watermarked results simultaneously. Custom watermarking is not supported for the time being.
options.watermark_info.enabled boolean No false true means to generate, false means not to generate

Supplementary Notes:

Kling Video 3.0 / 3.0 Turbo models can deliver a wide range of capabilities via prompts and other inputs:

  1. Multi-shot videos can be generated via a fixed format: "Shot n, m, words; Shot n, m, words;", separated by half-width symbols, where:

  2. n: Storyboard sequence number; supports a maximum of 6 storyboards and a minimum of 1 storyboard

  3. m: the duration of a storyboard shot; the duration of each storyboard shot shall be no less than 1, and the sum of the durations of all storyboard shots shall be equal to the total duration of the currently generated video

  4. words: storyboard prompt; maximum length 512

  5. Prompt templates can be used to meet different video generation requirements.

  6. For more information, please refer to the official Kling "Kling Video 3.0 Model User Guide" of Kling.

MaaS_KeLing_4.0_videoText-to-video: Not supported settings.multi_shot/ settings.audio; you can describe the purpose of creatives, segmented events and audio intent via Prompt, and reference creatives with @idin the contentsof Image-to-video/Omni (refer to the official "KeLing 4.0 User Guide" for details).

3.1.3 Response Parameters (Creation)

Parameter Name Field Type Description
code int Error code; for specific definitions, please refer to the error codes
message string Error Message
request_id string Request ID, generated by the system, for request tracking and troubleshooting
data.id string System-generated Task ID / Queried Task ID
data.status string Task status, enumerated values: submitted, processing, succeeded, failed
data.create_time long Task creation time, Unix timestamp, in ms
data.update_time long Task update time, Unix timestamp, in milliseconds
data.external_id string The custom task ID of this task (if any)

3.1.4 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/videos/text-to-video' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A girl sat on the train, looking out the window with a melancholic expression, her head swaying with the train.",
    "settings": {
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 5
    },
    "options": {
        "callback_url": "https://your.domain/callback",
        "external_task_id": "",
        "watermark_info": { "enabled": false }
    }
}'

3.1.5 Response Example

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "id": "893605946402811985",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151,
    "external_id": "string"
  }
}

3.2 Image to Video

3.2.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/videos/image-to-video

Applicable Models (endpoints): MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo/ MaaS_KeLing_4.0_video.

3.2.2 Request Body Parameters

Parameter Name Field Type Required or not default value Description
contents array Yes - A collection of reference creatives, such as prompts, images, subjects, timbres, etc. Please place the relevant fields of the same creative in the same directory structure.
contents[].type string Yes - Creatives type. Optional values by model: MaaS_KeLing_3.0_turbo: prompt, first_frame;
MaaS_KeLing_3.0_video: prompt, first_frame, last_frame, element;
MaaS_KeLing_V2.6: prompt, first_frame, last_frame, voice;
MaaS_KeLing_V2.5_turbo: prompt, first_frame, last_frame;
MaaS_KeLing_4.0_video supported values: prompt, first_frame, middle_frame, last_frame; does not support element, voice
contents[].text string No - type= promptthe text prompt. Length: MaaS_KeLing_3.0_videomust not exceed 3072 (recommended to be no more than 2500);
MaaS_KeLing_3.0_turbo/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbomust not exceed 2500;
MaaS_KeLing_4.0_videoThe rules are the same as in §3.1.2 promptlength specification
contents[].url string No - type= first_frame/ last_frame/ middle_frame (for MaaS_KeLing_4.0_videoonly): reference image, supports URL or Base64. Supported image formats:. jpg /. jpeg /. png;
MaaS_KeLing_3.0_turboto MaaS_KeLing_V2.5_turbo: ≤50MB, width and height ≥300px, aspect ratio 1:2.5 to 2.5:1;
MaaS_KeLing_4.0_videoImage: ≤30MB, width and height ≥300px, aspect ratio 2:5 to 5:2, total number of images ≤10
contents[].element_id string No - type= element, the subject ID (generated by the system and returned via subject-related API queries). Only MaaS_KeLing_3.0_videosupports this parameter; a maximum of 3 subjects can be specified.
MaaS_KeLing_4.0_videoText-to-image not supported element
contents[].voice_id string No - type= voice, the timbre ID (custom or preset). Only MaaS_KeLing_V2.6supports this parameter; up to 2 timbres can be referenced; when a timbre is specified, settings.audiocannot be set to off; specifying a timbre is not supported when generating a silent video. MaaS_KeLing_4.0_videodoes not support voice for image-to-video generation.
contents[].id string No - Creatives index ID, used to specify via @xxxin the prompt; the current parameter must not be duplicated within the same task. Applicable to the scenarios of subject (MaaS_KeLing_3.0_video) and voice (MaaS_KeLing_V2.6); recommended for multi-keyframe/multi-image scenarios of MaaS_KeLing_4.0_video
settings object No - Output configuration-related parameters, such as resolution, duration, etc.
settings.multi_shot boolean No true Whether to generate a multi-camera video. Only MaaS_KeLing_3.0_videosupports this feature; when set to false, multi-camera video cannot be generated even if a multi-camera format prompt is used. MaaS_KeLing_3.0_turbodoes not have this field, but multi-camera video can still be implemented via a fixed-format Prompt (see supplementary instructions).MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo/ MaaS_KeLing_4.0_videoNot supported (no optional values available, do not pass this field)
settings.audio string No off Whether to generate a video with audio. Supported values: native, off. This parameter is MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6only;MaaS_KeLing_3.0_turbo/ MaaS_KeLing_V2.5_turbo/ MaaS_KeLing_4.0_videodo not support this parameter (no valid values available, do not pass this field). For MaaS_KeLing_V2.6: only 1080P resolution is supported when generating a video with audio.Specifying a voice type is not supported when generating a silent video.
settings.resolution string No 720p The resolution of the generated video. Supported values: MaaS_KeLing_3.0_turbo/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbosupport 720p, 1080p;MaaS_KeLing_3.0_videosupports 720p, 1080p, 4K;MaaS_KeLing_4.0_videosupports: 720p, 1080p; default value: 1080p.MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo: When generating a video using the start and end frames, only 1080P video generation is supported;MaaS_KeLing_V2.6also only supports 1080P when audio is included.
settings.duration int No 5 Set the video generation duration in seconds. Available values: MaaS_KeLing_3.0_turbo/ MaaS_KeLing_3.0_video: 3–15;MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo: 5,10;MaaS_KeLing_4.0_videoOptional values: 3,4, 5,6, 7,8, 9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30; default 10
options object No - General configurations, such as callback URL, whether to include watermark, etc.
options.callback_url string No - This is the callback notification address for the result of this task. If configured, the server will actively send a notification when the task status changes. For the schema of the specific notification message, please refer to the Kling Callback Protocol.
options.external_task_id string No - Custom task ID. The passed-in ID will not overwrite the system-generated task ID, but you can use this ID to query tasks. Please note that this ID must be unique for a single user.
options.watermark_info object No - Specifies whether to generate watermarked results simultaneously. Custom watermarking is not supported for the time being.
options.watermark_info.enabled boolean No false true means to generate, false means not to generate

Supplementary Note (excerpted from official sources):

Frame Mode:

  • MaaS_KeLing_3.0_turbo: supports video generation from the first frame only, and does not support first frame + last frame or last frame only for now

  • MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6/ MaaS_KeLing_V2.5_turbo: support video generation from only the first frame image and from both the first and last frame images, do not support video generation from only the last frame image; the first frame is a required field, and the last frame is an optional field

Kling Video 3.0 / 3.0 Turbo models can deliver a wide range of capabilities via prompts and other inputs:

  1. Multi-shot videos can be generated via a fixed format: "Shot n, m, words; Shot n, m, words;", separated by half-width symbols, where:

  2. n: Storyboard sequence number; supports a maximum of 6 storyboards and a minimum of 1 storyboard

  3. m: the duration of a storyboard shot; the duration of each storyboard shot shall be no less than 1, and the sum of the durations of all storyboard shots shall be equal to the total duration of the currently generated video

  4. words: storyboard prompt; maximum length 512

  5. (MaaS_KeLing_3.0_video) You can specify a specific subject in the format of @xxx, for example:@Zhang

  6. (MaaS_KeLing_3.0_video) Please avoid inclusive relationships between different subject names, e.g., @Zhangand @ZhangSan

  7. (MaaS_KeLing_3.0_video) Please avoid the subject name being identical to part of the content in the Prompt, e.g.:@gmailand My email address is wang@gmail.com

  8. Prompt templates can be used to meet different video generation requirements.

  9. For more information, please refer to the official Kling "Kling Video 3.0 Model User Guide" of Kling.

MaaS_KeLing_V2.6: You can specify a certain timbre in the format of @xxx, for example:@sweet.

MaaS_KeLing_4.0_videoImage to video: Supports multiple keyframes (first frame / middle frame / last frame), with a maximum of 10 images; does not support settings.multi_shot, settings.audioand element/ voicecreatives.

3.2.3 Response Parameters

Same as §3.1.3.

3.2.4 Request Example (First Frame)

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/videos/image-to-video' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
        { "type": "prompt", "text": "A girl sat on the train, looking out the window with a melancholic expression, her head swaying with the train." },
        { "type": "first_frame", "url": "https://example.com/start-frame.jpg" }
    ],
    "settings": {
        "resolution": "1080p",
        "duration": 10
    },
    "options": {
        "callback_url": "https://your.domain/callback",
        "watermark_info": { "enabled": false }
    }
}'

3.2.5 Response Example

Same as §3.1.5.

3.3 Motion Control

3.3.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/motion-control

Applicable models (endpoints): MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6. The new protocol follows the structure of contents + settings + options; the path is aligned with the official specification, with no /videos prefix. The existing flat interface remains .../kling/videos/motion-control, which can be found in the historical documentation.This API does not have separate settings.duration/ settings.aspect_ratio/ settings.multi_shotparameters; the output duration is related to the reference video and valid motion extraction, and points will be deducted based on the duration of the output video.

3.3.2 Request Body Parameters

Parameter Name Field Type Required or not default value Description
contents array Yes - Reference creatives collection, such as prompts, image references, action reference videos, and subjects
contents[].type string Yes
 - Creatives type. Optional values: MaaS_KeLing_3for prompt, image, video, element; MaaS_KeLing_V2for prompt, image, video(no element)
contents[].text string No - type= prompt: the text prompt used in this scenario. You can use prompts to add elements to the frame, achieve camera movement effects, etc. ; the content length must not exceed 2500 characters.
contents[].url string No - type= imageindicates a visual reference image (supports URL or base64); when type= video, it refers to a motion reference video (only URL is supported, base64 is not supported)
contents[].element_id string No - type= elementthe subject ID at this time. Only MaaS_KeLing_3.0_videois supported; a maximum of 1 subject can be specified; when referencing a subject, the generated video can only temporarily refer to the character orientation in the video (character_orientationmust be video)
contents[].id string No - Creatives index ID; must not be duplicated within the same task (used for main scenarios)
settings object No - Output relevant configuration parameters, such as character orientation, clarity, etc.
settings.character_orientation string Yes - Specify the orientation of the person in the generated video. Accepted values: image (consistent with the person's orientation in the source image; the reference video must not exceed 10 seconds in this case), video (consistent with the person's orientation in the reference video; the reference video must not exceed 30 seconds). The minimum duration of the reference video is no less than 3 seconds.
settings.audio string No original Whether to generate a video with audio. Supported values: original (retain the original audio of the reference video), off (no audio included). Note: Motion control is not the native feature of text-to-video/image-to-video
settings.resolution string No 720p The clarity of the generated video. Supported values: 720p, 1080p (MaaS_KeLing_3.0_video/ MaaS_KeLing_V2.6are equivalent)
options object No - General configurations, such as callback URL, whether to include watermark, etc.
options.callback_url string No - This is the callback notification address for the result of this task. If configured, the server will actively send a notification when the task status changes. For the schema of the specific notification message, please refer to the Kling Callback Protocol.
options.external_task_id string No - Custom task ID. The passed-in ID will not overwrite the system-generated task ID, but you can use this ID to query tasks. Please note that this ID must be unique for a single user.
options.watermark_info object No - Specifies whether to generate watermarked results simultaneously. Custom watermarking is not supported for the time being.
options.watermark_info.enabled boolean No false true means to generate, false means not to generate

Supplementary Note (excerpted from official sources):

Content requirements for the image reference (image):

  • Try to keep the character proportions in the image consistent with those in the reference video, and avoid generating results by driving a half-body character with full-body motion data as much as possible.

  • The subject must have their clear upper body or full body (including limbs and head) fully visible, with no obstructions.

  • Avoid extreme orientations of the person in the frame, such as handstand, lying flat, etc. ; the proportion of the person in the frame shall not be too low.

  • Supports realistic/stylized characters, including human characters, anthropomorphic animals, some pure animals, and characters with partially anthropomorphic limb proportions

  • Supported image formats:. jpg /. jpeg /. png; file size must not exceed 50MB; width and height dimensions shall be no less than 300px; aspect ratio shall be within the range of 1:2.5 to 2.5:1

Content requirements for action reference video (video):

  • The subject must have their clear upper body or full body (including all limbs and head) fully visible, with no occlusion.

  • It is recommended to upload a video of a single person performing an action; if there are two or more people in the video, the action of the character occupying the largest proportion of the frame will be used for generation.

  • Live-action movements are recommended, and partially stylized human/human-like limb proportions can be achieved via

  • The action video is shot in a single continuous take, with the character always present in the frame; avoid camera cuts, camera movements, etc. , otherwise the footage will be clipped.

  • Avoid overly fast movements; relatively smooth movements yield better generation results.

  • If the action is highly difficult and fast-paced, there is a certain probability that the generated result will be shorter than the uploaded video duration; the model only extracts the valid action duration; a minimum of 3 seconds of usable continuous action is sufficient for generation. Points will be deducted based on the duration of the output video.

  • The system will verify the video content

  • Supported video formats: .mp4 / .mov; file size must not exceed 100MB; width and height dimensions: 340–3850px; duration ≥3s, the upper limit varies with character_orientation (video→ 30s / image→ 10s)

3.3.3–3.3.5 Responses / Examples

The response is created in the same manner as specified in §3.1.3.

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/motion-control' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
        { "type": "prompt", "text": "smooth dance motion" },
        { "type": "image", "url": "https://example.com/character.jpg" },
        { "type": "video", "url": "https://example.com/motion.mp4" }
    ],
    "settings": {
        "character_orientation": "video",
        "resolution": "1080p",
        "audio": "original"
    },
    "options": {
        "callback_url": "https://your.domain/callback"
    }
}'

3.4 Omni Video Generation

3.4.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/omni-video

Applicable Models (endpoints): MaaS_KeLing_3O_video/ MaaS_KeLing_O1_video/ MaaS_KeLing_4.0_video.

3.4.2 Request Body Parameters

Parameter Name Field Type Required or not default value Description
contents array Yes - Reference creatives collection, such as prompts, images, subjects, videos, timbres, etc.
contents[].type string Yes - Creatives type. MaaS_KeLing_3O_video / MaaS_KeLing_O1_video: prompt, first_frame, last_frame, refer_image, feature_video, base_video, element; MaaS_KeLing_4.0_video creatives type supported values: prompt, first_frame, middle_frame, last_frame, refer_image, feature_video, base_video, element, voice; no settings.multi_shot / settings.audio field.
contents[].text string No - type= promptspecifies the text prompt. Length requirements: MaaS_KeLing_3O_videomust not exceed 3072 (recommended to stay under 2500);MaaS_KeLing_O1_videomust not exceed 2500;MaaS_KeLing_4.0_videofollows the same rules as §3.1.2 promptlength specification
contents[].url string No - Image type (first_frame/ last_frame/ refer_image/ middle_frame (for MaaS_KeLing_4.0_videoonly)) supports URL or base64; for constraints on video type (feature_video/ base_video), refer to the supplementary instructions
contents[].element_id string No - type= elementindicates the subject ID. MaaS_KeLing_3O_videosupports both video character subjects and multi-image subjects;MaaS_KeLing_O1_videoonly supports multi-image subjects, and does not support video character subjects;MaaS_KeLing_4.0_videosupports both video character subjects and multi-image subjects: up to 7 subjects (with no more than 3 video character subjects); the total number of images, videos, subjects and timbres shall not exceed 15
contents[].voice_id string No - type= voicetone ID. Supported only by MaaS_KeLing_4.0_videoOmni (max 3; must set contentswith idand reference via @in Prompt)
contents[].id string No - Creatives index ID, used to specify in the prompt via @xxx (e. g. image @image_1, subject @Zhang, video @video_1, timbre @1); must not be duplicated within the same task
settings object No - Output configuration-related parameters, such as resolution, duration, etc.
settings.multi_shot boolean No true Whether to generate a multi-camera video. Only MaaS_KeLing_3O_videosupports this feature; when set to false, multi-camera videos cannot be generated even if a multi-camera format prompt is used. MaaS_KeLing_O1_video/ MaaS_KeLing_4.0_videodo not support this (no optional values available, please do not pass this field)
settings.audio string No off Specifies whether to generate a video with audio. Supported values: MaaS_KeLing_3O_videoaccepts native, original, off;MaaS_KeLing_O1_videoaccepts original, off (nativeis not supported). When using feature_video, simultaneous audio and video output is not supported, and audiocan only be set to off; when using base_video, audiocannot be set to native.MaaS_KeLing_4.0_videoNone settings.audiofield (the sound is described by Prompt)
settings.resolution string No 720p The resolution of the generated video. Supported values: MaaS_KeLing_3O_videosupports 720p, 1080p, 4k;MaaS_KeLing_O1_videosupports 720p, 1080p;MaaS_KeLing_4.0_videosupports: 720p, 1080p; default value is 1080p
settings.aspect_ratio string No 16:9 Specifies the aspect ratio (width: height) of the generated video. MaaS_KeLing_3O_video/ MaaS_KeLing_O1_videooptional values: 16:9, 9:16, 1:1 (required when no first frame and no reference video are provided; refer to the original documentation for rules);MaaS_KeLing_4.0_videooptional values: 21:9, 16:9, 9:16, 1:1, adaptive; default value: adaptive;If not provided or when adaptiveis selected, it can be inferred from Prompt / base_video/ keyframes and other sources
settings.duration int No 5 Duration of the generated video, in seconds. Supported values: MaaS_KeLing_3O_video: 3–15;MaaS_KeLing_O1_video: 3–10; when only the first frame is provided and no other reference images/videos are available, only 5 or 10 is supported.MaaS_KeLing_4.0_videoOptional values: 3,4, 5,6, 7,8, 9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30; default value 10; when base_videois present, its duration can be inherited
options object No - General configurations, such as callback URL, whether to include watermark, etc.
options.callback_url string No - This is the callback notification address for the result of this task. If configured, the server will actively send a notification when the task status changes. For the schema of the specific notification message, please refer to the Kling Callback Protocol.
options.external_task_id string No - Custom task ID. The passed-in ID will not overwrite the system-generated task ID, but you can use this ID to query tasks. Please note that this ID must be unique for a single user.
options.watermark_info object No - Specifies whether to generate watermarked results simultaneously. Custom watermarking is not supported for the time being.
options.watermark_info.enabled boolean No false true means to generate, false means not to generate

Supplementary Note (excerpted from official sources):

Keling Video 3.0 Omni model can deliver a wide range of capabilities via prompts and other inputs:

  1. Multi-shot videos can be generated via a fixed format: "Shot n, m, words; Shot n, m, words;", separated by half-width symbols, where:

  2. n: Storyboard sequence number; supports a maximum of 6 storyboards and a minimum of 1 storyboard

  3. m: the duration of a storyboard shot; the duration of each storyboard shot shall be no less than 1, and the sum of the durations of all storyboard shots shall be equal to the total duration of the currently generated video

  4. words: storyboard prompt; maximum length 512

  5. You can specify an image, a subject, or a video in the format of @xxx, for example:@image_1, @Zhang, @video_1

  6. Please avoid having an inclusive relationship between the names of different entities, for example:@Zhangand @ZhangSan

  7. Please avoid the subject name being identical to part of the content in the Prompt, for example:@gmailand the identical segment in email-related text

  8. For more information, please refer to the official Kling Omni User Guide

The Kling Video O1 model can deliver a wide range of capabilities via prompts and other inputs:

  1. You can specify an image, a subject, or a video in the format of @xxx, for example:@image_1, @Zhang, @video_1

  2. Please avoid an inclusive relationship between the names of different entities; please avoid the entity name being identical to part of the content in the Prompt.

  3. O1 does not have fixed multi-camera format instructions; for more information, please refer to the official Kling O1 user guide.

Images (first_frame / last_frame / refer_image):

  • Format: .jpg / .jpeg / .png; file size ≤ 50MB; width and height ≥ 300px; aspect ratio 1:2.5 \~ 2.5:1; URL or base64 supported

  • First/last frame: Supports only the first frame, and first + last frame; does not support only the last frame

  • MaaS_KeLing_O1_video: When using the start and end frames, adding more reference images is not supported; the subject is not supported when using the start and end frames

  • Maximum Number of Reference Images (in combination with the main subject):

  • MaaS_KeLing_3O_video: When no reference video is provided and only multi-image subjects are used, the total number of reference images plus multi-image subjects shall be ≤ 7; when no reference video is provided and both video character subjects and multi-image subjects are used, the total number shall be ≤ 4; when a reference video is provided and only multi-image subjects are used, the total number shall be ≤ 4;When a reference video is provided, video character subjects and reference images cannot be supported simultaneously

  • MaaS_KeLing_O1_video: When there is no reference video and there are multi-image subjects, the number of reference images plus multi-image subjects shall be ≤ 7; when there is a reference video and there are multi-image subjects, the number shall be ≤ 4

Videos (feature_video / base_video):

  • Format: .mp4 / .mov; File size ≤ 200MB; Maximum 1 reference video allowed

  • Duration: MaaS_KeLing_3O_videoranges from 3 to 15.5 seconds;MaaS_KeLing_O1_videoranges from 3 to 10 seconds

  • Resolution: MaaS_KeLing_3O_videowidth and height 700–4553px, total pixel area ≤8294400, aspect ratio 0.4–2;MaaS_KeLing_O1_videowidth and height 700–2160px

  • Frame rate: Input 24–60fps, output 24fps

  • feature_video: For multi-camera scenarios, multi_shotcan only be set to true; simultaneous audio and video output is not supported, and audiocan only be set to off. MaaS_KeLing_O1_videoonly supports defining the first frame of a video, and does not support defining the last frame.

  • base_video: does not support defining the first/last frame; does not support multi-shot;audiocannot be native

Subject (element):

  • MaaS_KeLing_3O_video: For the first frame or the first and last frame scenarios, there are at most 3 subjects; no video + multiple images only ≤ 7; no video + video characters only ≤ 3; no video + both, video characters ≤ 3 and images + multiple images ≤ 4; with video + multiple images only ≤ 4; with video + video characters only ≤ 1;When a reference video is provided, video character subjects and multi-image subjects are not supported simultaneously

  • MaaS_KeLing_O1_video: Only supports multi-image subjects; subjects are not supported when using the first and last frames; when there is no reference video, the total number of images + subjects shall be ≤7, and when there is a reference video, the total number shall be ≤4

Keling Video 4.0 Omni (MaaS_KeLing_4.0_video):

  1. Not supported: settings.multi_shot, settings.audio; multi-creatives referencing, video editing, lines, timbre and other related settings shall be described via Prompt + contents (including @id). For details, please refer to the official "Kling 4.0 User Guide".

  2. Images (including middle_frame/ refer_image, etc.): ≤30MB, width and height ≥300px, aspect ratio ranging from 2:5 to 5:2, total number of images ≤10; when there are multiple middle_frame/ refer_image, the idfield is required

  3. Video (feature_video / base_video): .mp4 / .mov, ≤300MB, 3–30s per segment (total input video duration includes the main video subject); refer to the official documentation for rules on the number of reference videos and subject combinations

  4. Subjects: up to 7 (video character subjects ≤ 3); voice types voice: maximum 3; total number of images + videos + subjects + voice types ≤ 15

3.4.3–3.4.5 Response / Examples

The response is created in the same manner as specified in §3.1.3.

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/omni-video' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
        { "type": "prompt", "text": "cinematic shot of the character walking in the rain" },
        { "type": "refer_image", "url": "https://example.com/ref.jpg", "id": "img1" }
    ],
    "settings": {
        "resolution": "1080p",
        "duration": 5,
        "aspect_ratio": "16:9",
        "audio": "off"
    },
    "options": {
        "callback_url": "https://your.domain/callback"
    }
}'

3.5 Query Task (General Protocol)

3.5.1 Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/general/tasks?task_id={id}

Or:

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/general/tasks?external_task_id={id}

Note: The current API only supports querying non-real-time / asynchronous tasks. task_idand external_task_id : you must select exactly one of the two IDs, and cannot use both at the same time. Platform adaptation: only supports querying a single task; the usage will only be settled for this single task (take billing[0], see §2.2). task_ids/ external_task_idswill be ignored if passed in (batch operation is not supported for the time being). The existing hard-coded Turbo query remains GET. ../kling/tasks (task_ids/ external_task_ids), see §3.6.

3.5.2 Request Query Parameters

Parameter Name Field Type Required or not default value Description
task_id string No - The task ID defined by the system to be queried (single). Either this or external_task_idis required.
external_task_id string No - The custom task ID to be queried (single). Either this or task_idshall be selected.
task_ids string No - Ignored; not supported yet
external_task_ids string No - Ignored; not supported yet

3.5.3 Response Parameters (Successful Task Summary)

Parameter Name Field Type Description
code int Error code; for specific definitions, please refer to the error codes
message string Error Message
request_id string Request ID, generated by the system, for request tracking and troubleshooting
data array Task List
data[].id string Queried Task ID
data[].status string Task status, enumerated values: submitted, processing, succeeded, failed
data[].create_time long Task creation time, Unix timestamp, in ms
data[].update_time long Task update time, Unix timestamp, in ms
data[].external_id string The custom task ID of this task (if any)
data[].outputs array Generation Result List (on Success)
data[].outputs[].type string Content type of the generation result; enumeration values: image, video, audio, element, voice; the returned fields will vary for different content types
data[].outputs[].url string URL of the generated result (Please note that for information security purposes, the generated images/videos will be cleared after 30 days, so please save them in time)
data[].outputs[].duration string Duration of the generated video, in seconds
data[].billing array For deduction details, see §2.1
data[].billing[].amount string Deduction amount; in the quota consumption scenario (charge_type= cash), it represents the discounted price deducted from the quota; in the resource package consumption scenario (charge_type= unit), it represents the points deduction amount; decimal

3.5.4 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/kling/general/tasks?task_id=893605946402811985' \
--header 'Authorization: Bearer {YOUR_AK}'