MaaS_KeLing_O3接口文档

请求协议

http

Header

视频接口

创建视频生成任务接口

请求URL

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

请求方法

POST

请求参数

multi_shot	boolean	可选	false	是否生成多镜头视频 ● 当前参数为 true 时，prompt 参数无效 ● 当前参数为 false 时，shot_type 参数及 multi_prompt 参数无效
shot_type	string	可选	空	分镜方式 ● 枚举值：customize ● 当 multi_shot 参数为 true 时，当前参数必填
prompt	string	可选	空	文本提示词，可包含正向描述和负向描述 ● 可将提示词模板化来满足不同的视频生成需求Omni模型可通过Prompt与主体、图片、视频等内容实现多种能力：  通过 <<<>>> 的格式来指定某个主体、图片、视频，如：<<<element_1>>>、<<<image_1>>>、<<<video_1>>>   ● 长度不能超过2500个字符 ● 当 multi_shot 参数为 false 或 shot_type 参数为 intelligence 时，当前参数不得为空 不同模型版本支持能力范围不同，详见上文能力地图
multi_prompt	array	可选	空	各分镜信息，如提示词、时长等 ● 通过 index、prompt、duration 参数定义分镜序号及相应提示词和时长，其中：   ○ 最多支持6个分镜，最小支持1个分镜   ○ 每个分镜相关内容的最大长度不超过512   ○ 每个分镜的时长不大于当前任务的总时长，不小于1  ○ 所有分镜的时长之和等于当前任务的总时长 ● 当 multi_shot 参数为 true 且 shot_type 参数为 customize 时，当前参数不得为空
image_list	array	可选	空	参考图列表 ● 包括主体、场景、风格等参考图片，也可作为首帧或尾帧生成视频；当作为首帧或尾帧生成视频时：   ○ 通过 type 参数来定义图片是否为首尾帧：first_frame 为首帧，end_frame 为尾帧     ■ 暂时不支持仅尾帧，即有尾帧图时必须有首帧图  ○ 使用首帧或首尾帧生成视频时，不能使用视频编辑功能； ● 支持传入图片 Base64 编码或图片 URL（确保可访问） ● 图片格式支持 .jpg / .jpeg / .png ● 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在 1:2.5 ~ 2.5:1 之间 ● 参考图片数量与有无参考视频、参考主体数量有关，其中：   ○ 有参考视频时，参考图片数量和参考主体数量之和不得超过4；   ○ 无参考视频时，参考图片数量和参考主体数量之和不得超过7；   ○ 参考图片数量超过2时，不支持设置尾帧； ● image_url 参数值不得为空 用key:value承载，如下： "image_list":[ { "image_url":"image_url", "type":"first_frame" }, { "image_url":"image_url", "type":"end_frame" } ] 不同模型版本支持能力范围不同，详见上文能力地图
element_list	array	可选	空	参考主体列表 ● 基于主体库中主体的 ID 配置，用key:value承载，如下： "element_list":[ { "element_id":long }, { "element_id":long } ] ● 参考主体数量与有无参考视频、参考图片数量有关，其中：   ○ 如果使用首帧生视频或首尾帧生视频时，最多支持3个主体；   ○ 有参考视频时，参考图片数量和参考主体数量之和不得超过4，且不支持使用视频角色主体；   ○ 无参考视频时，参考图片数量和参考主体数量之和不得超过7 ● 主体分为视频定制主体（简称：视频角色主体）和图片定制主体（简称：多图主体），适用范围不同，请注意区分 不同模型版本支持能力范围不同，详见上文能力地图
video_list	array	可选	空	参考视频，通过 URL 方式获取 ● 可作为特征参考视频，也可作为待编辑视频，默认为待编辑视频；可选择性保留视频原声   ○ 通过 refer_type 参数区分参考视频类型：feature 为特征参考视频，base 为待编辑视频   ○ 参考视频为待编辑视频时，不能定义视频首尾帧   ○ 通过 keep_original_sound 参数选择是否保留视频原声，yes 为保留，no 为不保留；当前参数对特征参考视频（feature）也生效 ● 有参考视频时，sound 参数值只能为 off ● 用key:value承载，如下： "video_list":[ { "video_url":"video_url", "refer_type":"base", "keep_original_sound":"yes" } ] ● 视频格式仅支持 MP4/MOV ● 视频时长不少于3秒，上限与模型版本有关，详见能力地图 ● 视频宽高尺寸需介于720px（含）和2160px（含）之间 ● 视频帧率基于24fps～60fps，生成视频时会输出为24fps ● 至多仅支持上传1段视频，视频大小不超过200MB ● video_url 参数值不得为空 不同模型版本支持能力范围不同，详见上文能力地图
sound	string	可选	off	生成视频时是否同时生成声音 ● 枚举值：on，off 仅 V2.6 及后续版本模型支持当前参数
mode	string	可选	pro	生成视频的模式 ● 枚举值：std，pro ● 其中 std：标准模式（标准），基础模式，生成720P视频，性价比高 ● 其中 pro：专家模式（高品质），高表现模式，生成1080P视频，视频质量更佳 不同模型版本支持能力范围不同，详见上文能力地图
aspect_ratio	string	可选	空	生成视频的画面纵横比（宽:高） ● 枚举值：16:9, 9:16, 1:1 ● 未使用首帧参考或视频编辑功能时，当前参数必填
duration	string	可选	5	生成视频时长，单位 s ● 枚举值：3，4，5，6，7，8，9，10，11，12，13，14，15，其中：  ○ 使用视频编辑功能（"refer_type":"base"）时，输出结果与传入视频时长相同，此时当前参数无效；此时，按输入视频时长四舍五入取整计量计费 不同模型版本支持能力范围不同，详见上文能力地图
watermark_info	array	可选	空	是否同时生成含水印的结果 ● 通过 enabled 参数定义 ● 用key:value承载，如下：： "watermark_info": { "enabled": boolean // true 为生成，false 为不生成 } ● 暂不支持自定义水印
external_task_id	string	可选	空	自定义任务ID ● 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询 ● 请注意，单用户下需要保证唯一性

请求示例

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"
  }'

返回值示例

{
  "code": 0, //错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data":{
        "task_id": "string" //任务ID，系统生成
        "task_info":{ //任务创建时的参数信息
            "external_task_id": "string"//客户自定义任务ID
        }, 
    "task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询视频任务接口

请求URL

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

请求方法

GET

请求参数

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data":{
          "task_id": "string", //任务ID，系统生成 
    "task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string"//客户自定义任务ID
    },
    "task_result":{
      "videos":[
        {
           "id": "string", //生成的视频ID；全局唯一
           "url": "string", //生成视频的URL，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
           "duration": "string", //视频总时长，单位s
           "watermark_url": "string"  //水印地址
        }
      ]
    },
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

图片生成

创建图片生成任务接口

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
prompt	string	必须	无	文本提示词，可包含正向描述和负向描述 ● 可将提示词模板化来满足不同的图像生成需求 ● 不能超过2500个字符
image_list	array	可选	空	参考图列表 ● 支持传入图片 Base64 编码或图片 URL（确保可访问） ● 图片格式支持 .jpg / .jpeg / .png ● 图片文件大小不能超过 10MB ● 图片宽高尺寸不小于 300px ● 图片宽高比要在 1:2.5 \~ 2.5:1 之间 ● 参考主体数量与参考图片数量有关，参考主体数量和参考图片数量之和不得超过 10 ● image_url 参数值不得为空
element_list	array	可选	空	主体参考列表 ● 基于主体库中主体的 ID 配置 ● 参考主体数量与参考图片数量有关，参考主体数量和参考图片数量之和不得超过 10
resolution	string	可选	1k	生成图片的清晰度 ● 枚举值：1k, 2k, 4k ○ 1k：1K标清 ○ 2k：2K高清 ○ 4k：4K高清 不同模型版本支持能力范围不同，详见上文能力地图
result_type	string	可选	single	生成结果单图/组图切换开关 ● 枚举值：single, series 不同模型版本支持范围不同，详见上文能力地图 ● 当 result_type 值为 series 时，当前参数无效
n	int	可选	1	生成图片数量 ● 取值范围：[1,9] ● 当 result_type 值为 series 时，当前参数无效
series_amount	int	可选	4	生成组图的图片数量 ● 取值范围：[2, 9] ● 当 result_type 值为 single 时，当前参数无效 不同模型版本支持范围不同，详见上文能力地图
aspect_ratio	string	可选	auto	生成图片的画面纵横比（宽:高） ● 枚举值：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, auto ○ 其中：auto 为根据传入内容智能生成视频 ○ 参考原图横纵比生成新图时，当前参数无效 不同模型版本支持范围不同，详见上文能力地图
watermark_info	array	可选	空	是否同时生成含水印的结果 ● 通过 enabled 参数定义 ● 暂不支持自定义水印
external_task_id	string	可选	无	自定义任务ID ● 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询 ● 请注意，单用户下需要保证唯一性

请求示例

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": ""
  }'

返回值示例

{
    "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"
}

查询图片任务接口

请求URL

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

请求方法

GET

请求参数

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data":{
    "task_id": "string", //任务ID，系统生成
    "task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { //任务创建时的参数信息
        "external_task_id": "string"//客户自定义任务ID
    },
    "task_result":{
            "images":[
              {
                "index": int, //图片编号，0-9
                "url": "string", //生成图片的URL，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
                "watermark_url": "string"  //水印地址
              }
            ]
    },
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}