MaaS_KeLing_O3 Interface Documentation

Request Protocol

http

Video Interface

Create Video Generation Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/omni-video

Request Method

POST

Request Parameters

`multi_shot`	boolean	Optional	`false`	Whether to generate multi-shot video ● When the current parameter is `true`, the `prompt` parameter is invalid ● When the current parameter is `false`, the `shot_type` parameter and the `multi_prompt` parameter are invalid
`shot_type`	string	Optional	Empty	Storyboard Method ● Enumerated value:`customize` ● When the `multi_shot` parameter is `true`, this parameter is required
`prompt`	string	Optional	Empty	Text prompt, which can include positive and negative descriptions ● The prompt can be templated to meet different video generation requirements. The Omni model can achieve various capabilities through Prompt with content such as subjects, images, and videos: `<<<>>>` format to specify a certain subject, image, or video, for example: `<<<element_1>>>`, `<<<image_1>>>`, `<<<video_1>>>` ● The length cannot exceed 2,500 characters ● When the `multi_shot` parameter is `false` or the `shot_type` parameter is `intelligence`, the current parameter must not be empty Different model versions support different ranges of capabilities. For details, see the capabilities map above.
`multi_prompt`	array	Optional	Empty	Information for each shot, such as prompts, duration, etc. ● Define the shot number, corresponding prompt, and duration through the `index`, `prompt`, `duration` parameters, where: ○ Supports up to 6 shots and at least 1 shot ○ The maximum length of each shot-related content does not exceed 512 ○ The duration of each shot is no greater than the total duration of the current task and no less than 1 ○ The sum of the durations of all storyboards equals the total duration of the current task ● When the `multi_shot` parameter is `true` and the `shot_type` parameter is `customize`, the current parameter must not be empty
`image_list`	array	Optional	Empty	Reference Diagram List ● Includes reference images such as subject, scene, style, etc., which can also be used as the first or last frame to generate a video; when used as the first or last frame to generate a video: ○ Define whether the image is the first or last frame through the `type` parameter: `first_frame` is the first frame, `end_frame` is the last frame. ■ Currently, only the last frame is not supported, i.e., when there is a last frame image, there must be a first frame image. ○ When generating a video using the first frame or both the first and last frames, video editing functions cannot be used; ● Supports passing in Base64-encoded images or image URLs (ensure they are accessible) ● Image format support `.jpg` / `.jpeg` / `.png` ● The size of the image file cannot exceed 10MB, the width and height of the image should be no less than 300px, and the aspect ratio of the image should be between 1:2.5 and 2.5:1. ● The number of reference images is related to the presence or absence of reference videos and the number of reference subjects, where: ○ When there is a reference video, the sum of the number of reference images and the number of reference subjects shall not exceed 4; ○ When there is no reference video, the sum of the number of reference images and the number of reference subjects shall not exceed 7; ○ When the number of reference images exceeds 2, setting the end frame is not supported; ● `image_url` parameter value must not be empty Carry it with key:value, as follows: `"image_list":[ { "image_url":"image_url", "type":"first_frame" }, { "image_url":"image_url", "type":"end_frame" } ]` Different model versions support different ranges of capabilities. For details, refer to the above Capability Map.
`element_list`	array	Optional	Empty	Reference Subject List ● Based on the ID configuration of the entities in the entity library, it is carried by key:value, as follows: `"element_list":[ { "element_id":long }, { "element_id":long } ]` ● The number of reference subjects is related to the presence of reference videos and the number of reference images, where: ○ When using the first frame to generate a video or the first and last frames to generate a video, a maximum of 3 subjects are supported; ○ When there is a reference video, the sum of the number of reference images and the number of reference subjects must not exceed 4, and the use of video character subjects is not supported; ○ When there is no reference video, the sum of the number of reference images and the number of reference subjects shall not exceed 7 ● The subjects are divided into video customization subjects (abbreviation: video character subjects) and image customization subjects (abbreviation: multi-image subjects), with different scopes of application. Please note the distinction. Different model versions support different ranges of capabilities, see the above capability map for details
`video_list`	array	Optional	Empty	Reference video, obtained via URL ● Can be used as a reference video for features or as a video to be edited, defaulting to a video to be edited; can optionally retain the original audio of the video ○ Distinguish the type of reference video through the `refer_type` parameter: `feature` is the feature reference video, `base` is the video to be edited ○ When the reference video is the video to be edited, the first and last frames of the video cannot be defined. ○ Select whether to keep the original audio of the video through the `keep_original_sound` parameter, `yes` means to keep it, `no` means not to keep it; the current parameter also takes effect on the feature reference video (`feature`). ● When there is a reference video, `sound` parameter value can only be `off` ● Use key:value to carry, as follows: `"video_list":[ { "video_url":"video_url", "refer_type":"base", "keep_original_sound":"yes" } ]` ● Video formats only support MP4/MOV ● Video duration is no less than 3 seconds, with the upper limit related to the model version. For details, refer to the Capability Map. ● The width and height dimensions of the video must be between 720px (inclusive) and 2160px (inclusive) ● Video frame rate is based on 24fps to 60fps, and will be output at 24fps when generating the video. ● Supports uploading at most 1 video, with the video size not exceeding 200MB ● `video_url` parameter value must not be empty Different model versions support different ranges of capabilities. For details, please refer to the capabilities map above.
`sound`	string	Optional	`off`	Whether to generate sound simultaneously when generating a video ● Enumerated values:`on`,`off` Only models of version V2.6 and later support the current parameters
`mode`	string	Optional	`pro`	Mode for generating videos ● Enumerated values:`std`,`pro` ● Among them, `std`: Standard Mode (Standard), basic mode, generates 720P video, high cost-performance ratio ● Among them, `pro`: Expert Mode (High Quality), High Performance Mode, generates 1080P videos with better video quality Different model versions support different ranges of capabilities. For details, please refer to the capabilities map above.
`aspect_ratio`	string	Optional	Empty	Aspect ratio (width:height) of the generated video ● Enumerated values: `16:9`, `9:16`, `1:1` ● When the first frame reference or video editing function is not used, the current parameter is required
`duration`	string	Optional	`5`	Generated video duration, unit: s ● Enumerated values: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, where: ○ When using the video editing function (`"refer_type":"base"`), the output result has the same duration as the input video, and the current parameters are invalid at this time; in this case, the billing is calculated based on the rounded duration of the input video Different model versions support different ranges of capabilities, see the above capability map for details
`watermark_info`	array	Optional	Empty	Whether to generate watermarked results simultaneously ● Defined by the `enabled` parameter ● Carried by key:value, as follows:: `"watermark_info": { "enabled": boolean // true 为生成，false 为不生成 }` ● Custom watermarks are not currently supported
`external_task_id`	string	Optional	Empty	Custom Task ID ● User-defined task ID. Passing it in will not overwrite the system-generated task ID, but it supports task querying via this ID. ● Please note that uniqueness must be ensured under single-user mode

Request Example

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{Your endpoint}/kling/videos/omni-video' \
--header 'Authorization: Bearer XXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "multi_shot": true,
    "shot_type": "customize",
    "prompt": "",
    "multi_prompt": [
      {
        "index": 1,
        "prompt": "A person sitting on a park bench, sunlight filtering through trees.  Simple composition, no dialogue.",
        "duration": "2"
      },
      {
        "index": 2,
        "prompt": "A car speeding down a rainy street, headlights glowing.  Dynamic angle, focus on motion.",
        "duration": "3"
      }
    ],
    "image_list": [],
    "video_list": [],
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "16:9",
    "duration": 5,  
    "external_task_id": "kling-v3-omni-video-test001"
  }'

Return Value Example


{
  "code": 0, //Error Code
  "message": "string", //Error Message
  "request_id": "string", //Request ID, system-generated for tracking and troubleshooting
  "data":{
        "task_id": "string" //Task ID, system-generated
        "task_info":{ //Parameters submitted when creating the task
            "external_task_id": "string"//Customer-defined Task ID
        }, 
    "task_status": "string", //Task Status，value：submitted、processing、succeed、failed
    "created_at": 1722769557708, //Task Creation Time, Unix Timestamp in milliseconds
    "updated_at": 1722769557708 //Task Update Time, Unix Timestamp in milliseconds
  }
}

Query Video Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/omni-video/{id}

Request Method

GET

Request Parameters

Return Value Example

{
  "code": 0, //
  "message": "string", //Error Message
  "request_id": "string", //Request ID, system-generated for tracking and troubleshooting
  "data":{
          "task_id": "string", //Task ID, system-generated
    "task_status": "string", //Task Status，value：submitted、processing、succeed、failed
    "task_status_msg": "string", //Task Status Information; shows failure reason when task fails (e.g., triggered platform content moderation, etc.)
    "task_info": { //Parameters submitted when creating the task
      "external_task_id": "string"//Customer-defined Task ID
    },
    "task_result":{
      "videos":[
        {
           "id": "string", //Generated Video ID, globally unique
           "url": "string", //Generated Video URL, anti-leech link format (Please note: To ensure information security, generated images/videos will be deleted after 30 days. Please save them promptly
           "duration": "string", //Total video duration in seconds
           "watermark_url": "string"  //Watermark URL
        }
      ]
    },
    "created_at": 1722769557708, //Task Creation Time, Unix Timestamp in milliseconds
    "updated_at": 1722769557708 //Task Update Time, Unix Timestamp in milliseconds
  }
}

Image Generation

Create Image Generation Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/images/omni-image

Request Method

POST

Request Parameters

Field	Type	Required	Default Value	Description
`prompt`	string	must	None	Text prompt, which can include positive and negative descriptions ● Prompts can be templated to meet different image generation requirements ● Must not exceed 2,500 characters
`image_list`	array	Optional	Empty	Reference Diagram List ● Supports passing in Base64-encoded images or image URLs (ensure they are accessible) ● Image formats supported:.jpg /.jpeg /.png ● The size of the image file cannot exceed 10MB ● The width and height of the image are not less than 300px ● The aspect ratio of the image should be between 1:2.5 and 2.5:1 ● The number of reference subjects is related to the number of reference images, and the sum of the number of reference subjects and the number of reference images must not exceed 10. ● The value of the image_url parameter must not be empty
`element_list`	array	Optional	Empty	Subject Reference List ● Configuration based on the ID of the entity in the entity library ● The number of reference subjects is related to the number of reference images, and the sum of the number of reference subjects and the number of reference images must not exceed 10.
`resolution`	string	Optional	`1k`	Clarity of the generated image ● Enumerated values: `1k`, `2k`, `4k` ○ `1k`: 1K Standard Definition ○ `2k`: 2K HD ○ `4k`: 4K Ultra HD Different model versions support different ranges of capabilities. For details, please refer to the capabilities map above.
`result_type`	string	Optional	`single`	Single Image/Group Image Switch for Generated Results ● Enumerated values:`single`, `series` Different model versions support different ranges; for details, see the above capabilities map ● When the value of result_type is series, the current parameter is invalid
`n`	int	Optional	`1`	Number of Generated Images ● Value range: [1, 9] ● When the value of result_type is series, the current parameter is invalid
`series_amount`	int	Optional	`4`	Number of images in the generated group of images ● Value range: [2, 9] ● When the value of result_type is single, the current parameter is invalid Different model versions support different ranges; for details, see the above capabilities map
`aspect_ratio`	string	Optional	`auto`	Aspect ratio (width:height) of the generated image ● Enumerated values:`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`, `auto` ○ Among them: auto means intelligently generating videos based on the input content ○ When generating a new image with reference to the aspect ratio of the original image, the current parameters are invalid Different model versions support different ranges; for details, see the above capabilities map
`watermark_info`	array	Optional	Empty	Whether to generate watermarked results simultaneously ● Defined by the enabled parameter ● Custom watermarks are not currently supported
`external_task_id`	string	Optional	None	Custom Task ID ● User-defined task ID. Passing it in will not overwrite the system-generated task ID, but it supports task query via this ID. ● Please note that uniqueness must be ensured under single-user mode

Request Example

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{Your endpoint}/kling/images/omni-image' \
--header 'Authorization: Bearer XXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "Generate a recommended cover for each subject <<object_1>>",
    "element_list": [
      {
        "element_id": "171"
      },
      {
        "element_id": "168"
      }
    ],
    "image_list": [],
    "resolution": "2k",
    "result_type": "series",
    "series_amount": 2,
    "aspect_ratio": "auto",
    "external_task_id": ""
  }'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788872612687921228",
        "task_status": "submitted",
        "created_at": 1756110406193,
        "updated_at": 1756110406193,
        "task_info": {
            "external_task_id": null
        }
    },
    "request_id": "227483a7-2a00-4028-ba42-21fc8bff3ffb"
}

Query Image Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/images/omni-image/{id}

Request Method

GET

Request Parameters

Return Value Example

{
  "code": 0, //error code
  "message": "string", //Error Message
  "request_id": "string", //Request ID, system-generated for tracking and troubleshooting
  "data":{
    "task_id": "string", //Task ID, system-generated
    "task_status": "string", //Task Status, values: submitted, processing, succeed, failed
    "task_status_msg": "string", //Task Status Information; shows failure reason when task fails (e.g., triggered platform content moderation, etc.
    "task_info": { //Parameters submitted when creating the task
        "external_task_id": "string"//Customer-defined Task ID
    },
    "task_result":{
            "images":[
              {
                "index": int, //Image Number, 0-9
                "url": "string", //Generated Image URL, anti-leech link format (Please note: To ensure information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
                "watermark_url": "string"  //Watermark URL
              }
            ]
    },
    "created_at": 1722769557708, //Task Creation Time, Unix Timestamp in milliseconds
    "updated_at": 1722769557708 //Task Update Time, Unix Timestamp in milliseconds
}

MaaS_KeLing_O3 Interface Documentation

Request Protocol

Header

Video Interface

Create Video Generation Task Interface

Request URL

Request Method

Request Parameters

Request Example

Return Value Example

Query Video Task Interface

Request URL

Request Method

Request Parameters

Return Value Example

Image Generation

Create Image Generation Task Interface

Request URL

Request Method

Request Parameters

Request Example

Return Value Example

Query Image Task Interface

Request URL

Request Method

Request Parameters

Return Value Example