KL_New_API

可灵通用协议 API（文生 / 图生 / 动作控制 / Omni）

1. 模型说明

能力	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
文生视频	✅	✅	✅	✅	—	—	✅
图生视频	✅	✅	✅	✅	—	—	✅
动作控制	—	✅	✅	—	—	—	—
Omni 视频	—	—	—	—	✅	✅	✅

各接口参数可选值、模型差异见 §3 对应参数表与补充说明。

2. 计费

2.1 平台的计费项与用量

计费项 code	用量计算
`credit`	取 `billing[0].amount` 作为本任务用量结算

3. 功能接口详情

3.1 文生视频

3.1.1 请求 url

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

适用模型（endpoint）：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 请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
prompt	string	是	-	文本提示词，可包含正向描述和负向描述。长度：`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_3.0_video` 不能超过 3072 个字符，建议不超过 2500；`MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` 不能超过 2500 个字符；`MaaS_KeLing_4.0_video`：纯英文 ≤26000 字符、纯非英文 ≤11000 字符；混合时英文字符数÷26000＋非英文字符数÷11000≤1。
settings	object	否	-	输出配置相关参数，如清晰度、时长等
settings.multi_shot	boolean	否	true	是否生成多镜头视频。仅 `MaaS_KeLing_3.0_video` 支持；当为 false 时，即便使用多镜头格式的 prompt 也无法生成多镜头视频。`MaaS_KeLing_3.0_turbo` 无此字段，但仍可通过 Prompt 固定格式实现多镜头（见补充说明）。`MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` / `MaaS_KeLing_4.0_video` 不支持（无可选值，请勿传该字段）
settings.audio	string	否	off	是否生成带有声音的视频。可选值：`native`、`off`。仅 `MaaS_KeLing_3.0_video` / `MaaS_KeLing_V2.6` 支持；`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_V2.5_turbo` / `MaaS_KeLing_4.0_video` 不支持（无可选值，请勿传该字段）。`MaaS_KeLing_V2.6`：生成有声视频时，仅支持 1080P 清晰度
settings.resolution	string	否	720p	生成视频的清晰度。可选值：`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` 为 `720p`、`1080p`；`MaaS_KeLing_3.0_video` 为 `720p`、`1080p`、`4k`；`MaaS_KeLing_4.0_video` 可选值：`720p`、`1080p`；默认 `1080p`；不支持 `4k`
settings.aspect_ratio	string	否	16:9	生成视频的画面纵横比（宽:高）。`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_3.0_video` / `MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` 可选值：`16:9`、`9:16`、`1:1`； `MaaS_KeLing_4.0_video` 可选值：`21:9`、`16:9`、`9:16`、`1:1`；默认 `16:9`
settings.duration	int	否	5	生成视频时长，单位 s。`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_video` 可选值：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；默认 `10`；未传时可从 Prompt 识别时长意图
options	object	否	-	通用配置，如回调地址、是否含水印等
options.callback_url	string	否	-	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息 schema 见可灵 Callback 协议。
options.external_task_id	string	否	-	自定义任务ID。传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性
options.watermark_info	object	否	-	是否同时生成含水印的结果。暂不支持自定义水印
options.watermark_info.enabled	boolean	否	false	true 为生成，false 为不生成

补充说明：

可灵视频 3.0 / 3.0 Turbo 模型可通过 Prompt 等内容实现多种能力：

可通过固定格式生成多镜头视频，格式为「镜头 n, m, words; 镜头 n, m, words;」，用半角符号分隔；其中：
n：分镜序号；最多支持 6 个分镜，最少支持 1 个分镜
m：分镜时长；每个分镜时长不小于 1，所有分镜时长之和等于当前所生成视频总时长
words：分镜提示词；最大长度 512
可将提示词模板化来满足不同的视频生成需求
更多信息详见可灵官方「可灵视频 3.0 模型使用指南」

MaaS_KeLing_4.0_video 文生：不支持 settings.multi_shot / settings.audio；可通过 Prompt 描述素材用途、分段事件与声音意图，并在图生/Omni 的 contents 中用 @id 引用素材（详见官方「可灵 4.0 使用指南」）。

3.1.3 响应参数（创建）

参数名	字段类型	描述
code	int	错误码；具体定义见错误码
message	string	错误信息
request_id	string	请求ID，系统生成，用于跟踪请求、排查问题
data.id	string	系统生成的任务ID / 被查询的任务ID
data.status	string	任务状态，枚举值：submitted（已提交）、processing（处理中）、succeeded（成功）、failed（失败）
data.create_time	long	任务创建时间，Unix时间戳、单位ms
data.update_time	long	任务更新时间，Unix时间戳、单位ms
data.external_id	string	该任务的自定义任务ID（如有）

3.1.4 请求示例

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 响应示例

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

3.2 图生视频

3.2.1 请求 url

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

适用模型（endpoint）：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 请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
contents	array	是	-	参考素材合集，如提示词、图片、主体、音色等。同一个素材的相关字段请放在同一个目录结构中
contents[].type	string	是	-	素材类型。可选值按模型：`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` 可选值：`prompt`、`first_frame`、`middle_frame`、`last_frame`；不支持 `element`、`voice`
contents[].text	string	否	-	type=`prompt` 时的文本提示词。长度：`MaaS_KeLing_3.0_video` 不能超过 3072（建议不超过 2500）； `MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` 不能超过 2500； `MaaS_KeLing_4.0_video` 规则同 §3.1.2 `prompt` 长度说明
contents[].url	string	否	-	type=`first_frame` / `last_frame` / `middle_frame`（仅 `MaaS_KeLing_4.0_video`）时的参考图，支持 url 或 base64。图片格式支持 .jpg / .jpeg / .png； `MaaS_KeLing_3.0_turbo`～`MaaS_KeLing_V2.5_turbo`：≤50MB，宽高 ≥300px，宽高比 1:2.5～2.5:1； `MaaS_KeLing_4.0_video` 图：≤30MB，宽高 ≥300px，宽高比 2:5～5:2，图片总数 ≤10
contents[].element_id	string	否	-	type=`element` 时的主体 ID（由系统生成，通过查询主体相关 API 返回）。仅 `MaaS_KeLing_3.0_video` 支持；最多支持指定 3 个主体。 `MaaS_KeLing_4.0_video` 图生不支持 `element`
contents[].voice_id	string	否	-	type=`voice` 时的音色 ID（音色定制或预置）。仅 `MaaS_KeLing_V2.6` 支持；至多引用 2 个音色；指定音色时 `settings.audio` 不能为 `off`；生成无声视频时不支持指定音色。`MaaS_KeLing_4.0_video` 图生不支持 `voice`
contents[].id	string	否	-	素材索引 ID，用于在 prompt 中通过 `@xxx` 指定；同任务中当前参数不得重复。主体（`MaaS_KeLing_3.0_video`）与音色（`MaaS_KeLing_V2.6`）场景使用；`MaaS_KeLing_4.0_video` 多关键帧/多图场景建议使用
settings	object	否	-	输出配置相关参数，如清晰度、时长等
settings.multi_shot	boolean	否	true	是否生成多镜头视频。仅 `MaaS_KeLing_3.0_video` 支持；为 false 时即便使用多镜头格式 prompt 也无法生成多镜头。`MaaS_KeLing_3.0_turbo` 无此字段，但仍可通过 Prompt 固定格式实现多镜头（见补充说明）。`MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` / `MaaS_KeLing_4.0_video` 不支持（无可选值，请勿传该字段）
settings.audio	string	否	off	是否生成带有声音的视频。可选值：`native`、`off`。仅 `MaaS_KeLing_3.0_video` / `MaaS_KeLing_V2.6` 支持；`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_V2.5_turbo` / `MaaS_KeLing_4.0_video` 不支持（无可选值，请勿传该字段）。`MaaS_KeLing_V2.6`：生成有声视频时仅支持 1080P；生成无声视频时不支持指定音色
settings.resolution	string	否	720p	生成视频的清晰度。可选值：`MaaS_KeLing_3.0_turbo` / `MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo` 为 `720p`、`1080p`；`MaaS_KeLing_3.0_video` 为 `720p`、`1080p`、`4k`；`MaaS_KeLing_4.0_video` 可选值：`720p`、`1080p`；默认 `1080p`。`MaaS_KeLing_V2.6` / `MaaS_KeLing_V2.5_turbo`：使用首尾帧生成视频时，仅支持生成 1080P 视频；`MaaS_KeLing_V2.6` 有声时亦仅支持 1080P
settings.duration	int	否	5	生成视频时长，单位 s。可选值：`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_video` 可选值：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；默认 `10`
options	object	否	-	通用配置，如回调地址、是否含水印等
options.callback_url	string	否	-	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息 schema 见可灵 Callback 协议。
options.external_task_id	string	否	-	自定义任务ID。传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性
options.watermark_info	object	否	-	是否同时生成含水印的结果。暂不支持自定义水印
options.watermark_info.enabled	boolean	否	false	true 为生成，false 为不生成

补充说明（摘自官方）：

帧模式：

MaaS_KeLing_3.0_turbo：支持仅首帧图生视频，暂不支持首帧+尾帧和仅尾帧
MaaS_KeLing_3.0_video / MaaS_KeLing_V2.6 / MaaS_KeLing_V2.5_turbo：支持仅首帧图生视频和首尾帧图生视频，不支持仅尾帧图生视频；首帧时必填，尾帧时选填

可灵视频 3.0 / 3.0 Turbo 模型可通过 Prompt 等内容实现多种能力：

可通过固定格式生成多镜头视频，格式为「镜头 n, m, words; 镜头 n, m, words;」，用半角符号分隔；其中：
n：分镜序号；最多支持 6 个分镜，最少支持 1 个分镜
m：分镜时长；每个分镜时长不小于 1，所有分镜时长之和等于当前所生成视频总时长
words：分镜提示词；最大长度 512
（MaaS_KeLing_3.0_video）可通过 @xxx 的格式来指定某个主体，如：@Zhang
（MaaS_KeLing_3.0_video）请避免不同主体名称存在包含关系，如：@Zhang 与 @ZhangSan
（MaaS_KeLing_3.0_video）请避免主体名称与 Prompt 中部分内容雷同，如：@gmail 与 My email address is wang@gmail.com
可将提示词模板化来满足不同的视频生成需求
更多信息详见可灵官方「可灵视频 3.0 模型使用指南」

MaaS_KeLing_V2.6： 可通过 @xxx 的格式来指定某个音色，如：@sweet。

MaaS_KeLing_4.0_video 图生：支持多关键帧（首帧 / 中间帧 / 尾帧），图片最多 10 张；不支持 settings.multi_shot、settings.audio 与 element / voice 素材。

3.2.3 响应参数

同 §3.1.3。

3.2.4 请求示例（首帧）

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 响应示例

同 §3.1.5。

3.3 动作控制

3.3.1 请求 url

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

适用模型（endpoint）：MaaS_KeLing_3.0_video / MaaS_KeLing_V2.6。新契约为 contents + settings + options；路径对齐官方，无/videos 前缀。存量扁平接口仍为 .../kling/videos/motion-control，见历史文档。本接口无独立 settings.duration / settings.aspect_ratio / settings.multi_shot；输出时长跟参考视频及有效动作提取有关，积分扣减以输出视频时长为准。

3.3.2 请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
contents	array	是	-	参考素材合集，如提示词、形象参考图、动作参考视频、主体
contents[].type	string	是	-	素材类型。可选值：`MaaS_KeLing_3.0_video` 为 `prompt`、`image`、`video`、`element`；`MaaS_KeLing_V2.6` 为 `prompt`、`image`、`video`（无 `element`）
contents[].text	string	否	-	type=`prompt` 时的文本提示词。可通过提示词为画面增加元素、实现运镜效果等；内容长度不能超过 2500 个字符
contents[].url	string	否	-	type=`image` 时为形象参考图（支持 url 或 base64）；type=`video` 时为动作参考视频（仅支持 url，不支持 base64）
contents[].element_id	string	否	-	type=`element` 时的主体 ID。仅 `MaaS_KeLing_3.0_video` 支持；最多指定 1 个主体；引用主体时，生成的视频暂时只能参考视频中的人物朝向（`character_orientation` 须为 `video`）
contents[].id	string	否	-	素材索引 ID；同任务中不得重复（主体场景使用）
settings	object	否	-	输出配置相关参数，如人物朝向、清晰度等
settings.character_orientation	string	是	-	生成视频中人物的朝向。可选值：`image`（与图片中人物朝向一致；此时参考视频时长不得超过 10 秒）、`video`（与视频中人物朝向一致；参考视频时长不得超过 30 秒）。参考视频时长下限 ≥3 秒
settings.audio	string	否	original	是否生成带有声音的视频。可选值：`original`（保留参考视频原声）、`off`（不含声音）。注意：动作控制不是文生/图生的 `native`
settings.resolution	string	否	720p	生成视频的清晰度。可选值：`720p`、`1080p`（`MaaS_KeLing_3.0_video` / `MaaS_KeLing_V2.6` 相同）
options	object	否	-	通用配置，如回调地址、是否含水印等
options.callback_url	string	否	-	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息 schema 见可灵 Callback 协议。
options.external_task_id	string	否	-	自定义任务ID。传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性
options.watermark_info	object	否	-	是否同时生成含水印的结果。暂不支持自定义水印
options.watermark_info.enabled	boolean	否	false	true 为生成，false 为不生成

补充说明（摘自官方）：

形象参考图（image）内容要求：

图片中人物比例尽量与参考视频中人物比例一致，尽量避免全身动作驱动半身人物进行生成
人物需要露出清晰的上半身或全身的肢体及头部，避免遮挡
画面中人物避免存在极端朝向，比如倒立、平卧等；人物占画面比例不得太低
支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）
图片格式支持 .jpg / .jpeg / .png；文件大小不能超过 50MB；宽高尺寸不小于 300px；宽高比要在 1:2.5 \~ 2.5:1 之间

动作参考视频（video）内容要求：

人物需要露出清晰的上半身或全身的全部肢体及头部，避免遮挡
建议上传 1 人动作视频，2 人及以上会取画面占比最大的人物动作进行生成
推荐使用真人动作，部分风格化的人物/类人肢体比例可以通过
动作视频一镜到底，角色始终出现在画面中，避免切镜、运镜等，否则会被截取
动作避免过快，相对平稳的动作生成效果更佳
若动作难度高、速度快，有一定概率生成不足上传视频时长的结果；模型只提取有效动作时长；最短提取出 3s 可用连续动作即可生成；积分扣减以输出视频时长为准
系统会校验视频内容
视频格式支持 .mp4 / .mov；文件大小不能超过 100MB；宽高尺寸 340～3850px；时长 ≥3s，上限随 character_orientation（video→30s / image→10s）

3.3.3～3.3.5 响应 / 示例

创建响应同 §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 视频生成

3.4.1 请求 url

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

适用模型（endpoint）：MaaS_KeLing_3O_video / MaaS_KeLing_O1_video / MaaS_KeLing_4.0_video。

3.4.2 请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
contents	array	是	-	参考素材合集，如提示词、图片、主体、视频、音色等
contents[].type	string	是	-	素材类型。`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` 素材 type 可选值：`prompt`、`first_frame`、`middle_frame`、`last_frame`、`refer_image`、`feature_video`、`base_video`、`element`、`voice`；无 `settings.multi_shot` / `settings.audio` 字段。
contents[].text	string	否	-	type=`prompt` 时的文本提示词。长度：`MaaS_KeLing_3O_video` 不能超过 3072（建议不超过 2500）；`MaaS_KeLing_O1_video` 不能超过 2500；`MaaS_KeLing_4.0_video` 规则同 §3.1.2 `prompt` 长度说明
contents[].url	string	否	-	图片类（`first_frame` / `last_frame` / `refer_image` / `middle_frame`（仅 `MaaS_KeLing_4.0_video`））支持 url 或 base64；视频类（`feature_video` / `base_video`）约束见补充说明
contents[].element_id	string	否	-	type=`element` 时的主体 ID。`MaaS_KeLing_3O_video` 支持视频角色主体 + 多图主体；`MaaS_KeLing_O1_video`仅支持多图主体，不支持视频角色主体；`MaaS_KeLing_4.0_video` 支持视频角色主体与多图主体：最多 7 个主体（其中视频角色主体 ≤3）；图片+视频+主体+音色合计 ≤15
contents[].voice_id	string	否	-	type=`voice` 时的音色 ID。仅 `MaaS_KeLing_4.0_video` Omni 支持（至多 3 个；须在 `contents` 中设置 `id` 并在 Prompt 中 `@` 引用）
contents[].id	string	否	-	素材索引 ID，用于在 prompt 中通过 `@xxx` 指定（如图片 `@image_1`、主体 `@Zhang`、视频 `@video_1`、音色 `@1`）；同任务中不得重复
settings	object	否	-	输出配置相关参数，如清晰度、时长等
settings.multi_shot	boolean	否	true	是否生成多镜头视频。仅 `MaaS_KeLing_3O_video` 支持；为 false 时即便使用多镜头格式 prompt 也无法生成多镜头。`MaaS_KeLing_O1_video` / `MaaS_KeLing_4.0_video` 不支持（无可选值，请勿传该字段）
settings.audio	string	否	off	是否生成带有声音的视频。可选值：`MaaS_KeLing_3O_video` 为 `native`、`original`、`off`；`MaaS_KeLing_O1_video` 为 `original`、`off`（无 `native`）。使用 `feature_video` 时不支持音画同出，`audio` 只能为 `off`；使用 `base_video` 时 `audio` 不能为 `native`。`MaaS_KeLing_4.0_video` 无 `settings.audio` 字段（声音由 Prompt 描述）
settings.resolution	string	否	720p	生成视频的清晰度。可选值：`MaaS_KeLing_3O_video` 为 `720p`、`1080p`、`4k`；`MaaS_KeLing_O1_video` 为 `720p`、`1080p`；`MaaS_KeLing_4.0_video` 可选值：`720p`、`1080p`；默认 `1080p`
settings.aspect_ratio	string	否	16:9	生成视频的画面纵横比（宽:高）。`MaaS_KeLing_3O_video` / `MaaS_KeLing_O1_video` 可选 `16:9`、`9:16`、`1:1`（无首帧且无参考视频时必填，规则见原说明）；`MaaS_KeLing_4.0_video` 可选值：`21:9`、`16:9`、`9:16`、`1:1`、`adaptive`；默认 `adaptive`；未传或传 `adaptive` 时可从 Prompt / `base_video` / 关键帧等推断
settings.duration	int	否	5	生成视频时长，单位 s。可选值：`MaaS_KeLing_3O_video` 为 3～15；`MaaS_KeLing_O1_video` 为 3～10，且当仅首帧且无其它参考图/视频时仅支持 5 或 10；`MaaS_KeLing_4.0_video` 可选值：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；默认 `10`；有 `base_video` 时可继承其时长
options	object	否	-	通用配置，如回调地址、是否含水印等
options.callback_url	string	否	-	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息 schema 见可灵 Callback 协议。
options.external_task_id	string	否	-	自定义任务ID。传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性
options.watermark_info	object	否	-	是否同时生成含水印的结果。暂不支持自定义水印
options.watermark_info.enabled	boolean	否	false	true 为生成，false 为不生成

补充说明（摘自官方）：

可灵视频 3.0 Omni 模型可通过 Prompt 等内容实现多种能力：

可通过固定格式生成多镜头视频，格式为「镜头 n, m, words; 镜头 n, m, words;」，用半角符号分隔；其中：
n：分镜序号；最多支持 6 个分镜，最少支持 1 个分镜
m：分镜时长；每个分镜时长不小于 1，所有分镜时长之和等于当前所生成视频总时长
words：分镜提示词；最大长度 512
可通过 @xxx 的格式来指定某张图片、某个主体、某个视频，如：@image_1、@Zhang、@video_1
请避免不同主体名称存在包含关系，如：@Zhang 与 @ZhangSan
请避免主体名称与 Prompt 中部分内容雷同，如：@gmail 与邮箱类文本中的同名片段
更多信息详见可灵官方 Omni 使用指南

可灵视频 O1 模型可通过 Prompt 等内容实现多种能力：

可通过 @xxx 的格式来指定某张图片、某个主体、某个视频，如：@image_1、@Zhang、@video_1
请避免不同主体名称存在包含关系；请避免主体名称与 Prompt 中部分内容雷同
O1 无多镜头固定格式说明；更多信息详见可灵官方 O1 使用指南

图片（first_frame / last_frame / refer_image）：

格式 .jpg / .jpeg / .png；≤50MB；宽高 ≥300px；宽高比 1:2.5 \~ 2.5:1；支持 url 或 base64
首/尾帧：支持仅首帧、首+尾帧；不支持仅尾帧
MaaS_KeLing_O1_video：使用首尾帧时，不支持添加更多参考图；使用首尾帧时不支持主体
参考图数量上限（与主体组合）：
MaaS_KeLing_3O_video：无参考视频+仅多图主体时，参考图+多图主体 ≤7；无参考视频+视频角色主体+多图主体时 ≤4；有参考视频+仅多图主体时 ≤4；有参考视频时，不同时支持视频角色主体和参考图片
MaaS_KeLing_O1_video：无参考视频+有多图主体时，参考图+多图主体 ≤7；有参考视频+有多图主体时 ≤4

视频（feature_video / base_video）：

格式 .mp4 / .mov；≤200MB；最多 1 段参考视频
时长：MaaS_KeLing_3O_video 为 3～15.5s；MaaS_KeLing_O1_video 为 3～10s
分辨率：MaaS_KeLing_3O_video 宽高 700～4553px，像素总面积 ≤8294400，宽高比 0.4～2；MaaS_KeLing_O1_video 宽高 700～2160px
帧率：输入 24～60fps，输出 24fps
feature_video：多镜头时 multi_shot 只能为 true；不支持音画同出，audio 只能为 off。MaaS_KeLing_O1_video 仅支持定义视频首帧，不支持尾帧
base_video：不支持定义首/尾帧；不支持多镜头；audio 不能为 native

主体（element）：

MaaS_KeLing_3O_video：首帧或首尾帧场景最多 3 主体；无视频+仅多图 ≤7；无视频+仅视频角色 ≤3；无视频+两者时视频角色 ≤3 且图+多图 ≤4；有视频+仅多图 ≤4；有视频+仅视频角色 ≤1；有参考视频时不同时支持视频角色主体和多图主体
MaaS_KeLing_O1_video：仅多图主体；使用首尾帧时不支持主体；无参考视频时图+主体 ≤7，有参考视频时 ≤4

可灵视频 4.0 Omni（MaaS_KeLing_4.0_video）：

不支持 settings.multi_shot、settings.audio；多素材引用、视频编辑、台词与音色等通过 Prompt + contents（含 @id）描述，详见官方「可灵 4.0 使用指南」
图片（含 middle_frame / refer_image 等）：≤30MB，宽高 ≥300px，宽高比 2:5～5:2，图片总数 ≤10；多张 middle_frame / refer_image 时 id 必填
视频（feature_video / base_video）：.mp4 / .mov，≤300MB，单段 3～30s（总输入视频时长含视频角色主体）；参考视频数量与主体组合规则见官方文档
主体：最多 7 个（视频角色主体 ≤3）；音色 voice 至多 3 个；图片+视频+主体+音色合计 ≤15

3.4.3～3.4.5 响应 / 示例

创建响应同 §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 查询任务（通用协议）

3.5.1 请求 url

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

或：

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

注意：当前API仅支持查询非实时/异步任务。 task_id 与 external_task_id 两种 ID 至少且只能选择一种，不可同时使用。 平台适配：仅支持查询单个任务；用量仅结算该单个任务（取 billing[0]，见 §2.2）。 task_ids / external_task_ids 若传入则忽略（暂不支持批量）。存量写死 Turbo 查询仍为 GET .../kling/tasks（task_ids / external_task_ids），见 §3.6。

3.5.2 请求 query 参数

参数名	字段类型	是否必填	默认值	描述
task_id	string	否	-	需要查询的系统定义的任务ID（单个）。与 `external_task_id` 二选一
external_task_id	string	否	-	需要查询的自定义任务ID（单个）。与 `task_id` 二选一
task_ids	string	否	-	忽略；暂不支持
external_task_ids	string	否	-	忽略；暂不支持

3.5.3 响应参数（成功任务摘要）

参数名	字段类型	描述
code	int	错误码；具体定义见错误码
message	string	错误信息
request_id	string	请求ID，系统生成，用于跟踪请求、排查问题
data	array	任务列表
data[].id	string	被查询的任务ID
data[].status	string	任务状态，枚举值：submitted（已提交）、processing（处理中）、succeeded（成功）、failed（失败）
data[].create_time	long	任务创建时间，Unix 时间戳，单位 ms
data[].update_time	long	任务更新时间，Unix 时间戳，单位 ms
data[].external_id	string	该任务的自定义任务ID（如有）
data[].outputs	array	生成结果列表（成功时）
data[].outputs[].type	string	生成结果内容类型；枚举值：image, video, audio, element, voice；不同内容类型返回字段会有区别
data[].outputs[].url	string	生成结果的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
data[].outputs[].duration	string	生成的视频的时长，单位：秒
data[].billing	array	扣减明细，见 §2.1
data[].billing[].amount	string	扣减数额；消耗额度场景（charge_type=cash）时代表额度扣减折扣价，消耗资源包场景（charge_type=unit）时代表积分扣减量；十进制

3.5.4 请求示例

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