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

模型说明

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

功能接口详情

文生视频

请求 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。

请求 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 个字符
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` 不支持
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_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`
settings.aspect_ratio	string	否	16:9	生成视频的画面纵横比（宽:高）。可选值：`16:9`、`9:16`、`1:1`（上述文生模型均支持）
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
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) 更多信息详见可灵官方「可灵视频 3.0 模型使用指南」

响应参数（创建）

参数名	字段类型	描述
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（如有）

请求示例

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

响应示例

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

图生视频

请求 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。

请求 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`
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
contents[].url	string	否	-	type=`first_frame` / `last_frame` 时的参考图，支持 url 或 base64。图片格式支持 .jpg / .jpeg / .png；文件大小不能超过 50MB；宽高尺寸不小于 300px；宽高比要在 1:2.5 \~ 2.5:1 之间
contents[].element_id	string	否	-	type=`element` 时的主体 ID（由系统生成，通过查询主体相关 API 返回）。仅 `MaaS_KeLing_3.0_video` 支持；最多支持指定 3 个主体
contents[].voice_id	string	否	-	type=`voice` 时的音色 ID（音色定制或预置）。仅 `MaaS_KeLing_V2.6` 支持；至多引用 2 个音色；指定音色时 `settings.audio` 不能为 `off`；生成无声视频时不支持指定音色
contents[].id	string	否	-	素材索引 ID，用于在 prompt 中通过 `@xxx` 指定；同任务中当前参数不得重复。主体（`MaaS_KeLing_3.0_video`）与音色（`MaaS_KeLing_V2.6`）场景使用
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` 不支持
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_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_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
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

3) （MaaS_KeLing_3.0_video）请避免不同主体名称存在包含关系，如：@Zhang 与 @ZhangSan

4) （MaaS_KeLing_3.0_video）请避免主体名称与 Prompt 中部分内容雷同，如：@gmail 与 My email address is wang@gmail.com

可将提示词模板化来满足不同的视频生成需求
更多信息详见可灵官方「可灵视频 3.0 模型使用指南」

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

请求示例（首帧）

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

动作控制

请求 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 前缀。

请求 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）

响应 / 示例

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

Omni 视频生成

请求 url

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

适用模型（endpoint）：MaaS_KeLing_3.0_video-omni / MaaS_KeLing_O1_video。

请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
contents	array	是	-	参考素材合集，如提示词、图片、主体、视频等
contents[].type	string	是	-	素材类型。可选值（两模型相同）：`prompt`、`first_frame`、`last_frame`、`refer_image`、`feature_video`、`base_video`、`element`
contents[].text	string	否	-	type=`prompt` 时的文本提示词。长度：`MaaS_KeLing_3.0_video-omni` 不能超过 3072（建议不超过 2500）；`MaaS_KeLing_O1_video` 不能超过 2500
contents[].url	string	否	-	图片类（`first_frame` / `last_frame` / `refer_image`）支持 url 或 base64；视频类（`feature_video` / `base_video`）约束见补充说明
contents[].element_id	string	否	-	type=`element` 时的主体 ID。`MaaS_KeLing_3.0_video-omni` 支持视频角色主体 + 多图主体；`MaaS_KeLing_O1_video` 仅支持多图主体，不支持视频角色主体。数量上限与是否搭配参考视频/首尾帧见补充说明
contents[].id	string	否	-	素材索引 ID，用于在 prompt 中通过 `@xxx` 指定（如图片 `@image_1`、主体 `@Zhang`、视频 `@video_1`）；同任务中不得重复
settings	object	否	-	输出配置相关参数，如清晰度、时长等
settings.multi_shot	boolean	否	true	是否生成多镜头视频。仅 `MaaS_KeLing_3.0_video-omni` 支持；为 false 时即便使用多镜头格式 prompt 也无法生成多镜头。`MaaS_KeLing_O1_video` 不支持
settings.audio	string	否	off	是否生成带有声音的视频。可选值：`MaaS_KeLing_3.0_video-omni` 为 `native`、`original`、`off`； `MaaS_KeLing_O1_video` 为 `original`、`off`（无 `native`）。使用 `feature_video` 时不支持音画同出，`audio` 只能为 `off`；使用 `base_video` 时 `audio` 不能为 `native`
settings.resolution	string	否	720p	生成视频的清晰度。可选值：`MaaS_KeLing_3.0_video-omni` 为 `720p`、`1080p`、`4k`； `MaaS_KeLing_O1_video` 为 `720p`、`1080p`
settings.aspect_ratio	string	否	16:9	生成视频的画面纵横比（宽:高）。可选值：`16:9`、`9:16`、`1:1`。`MaaS_KeLing_3.0_video-omni`：当没有首帧图或没有参考视频时，当前参数必填；`MaaS_KeLing_O1_video`：当没有首帧图且没有参考视频时，当前参数必填
settings.duration	int	否	5	生成视频时长，单位 s。可选值：`MaaS_KeLing_3.0_video-omni` 为 3～15；`MaaS_KeLing_O1_video` 为 3～10，且当仅首帧且无其它参考图/视频时仅支持 5 或 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 为不生成

补充说明（摘自官方）：

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

可通过固定格式生成多镜头视频，格式为「镜头 n, m, words; 镜头 n, m, words;」，用半角符号分隔；其中：
n：分镜序号；最多支持 6 个分镜，最少支持 1 个分镜
m：分镜时长；每个分镜时长不小于 1，所有分镜时长之和等于当前所生成视频总时长
words：分镜提示词；最大长度 512
可通过 @xxx 的格式来指定某张图片、某个主体、某个视频，如：@image_1、@Zhang、@video_1

3) 请避免不同主体名称存在包含关系，如：@Zhang 与 @ZhangSan

4) 请避免主体名称与 Prompt 中部分内容雷同，如：@gmail 与邮箱类文本中的同名片段

更多信息详见可灵官方 Omni 使用指南

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

可通过 @xxx 的格式来指定某张图片、某个主体、某个视频，如：@image_1、@Zhang、@video_1
请避免不同主体名称存在包含关系；请避免主体名称与 Prompt 中部分内容雷同

3) 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_3.0_video-omni：无参考视频+仅多图主体时，参考图+多图主体 ≤7；无参考视频+视频角色主体+多图主体时 ≤4；有参考视频+仅多图主体时 ≤4；有参考视频时，不同时支持视频角色主体和参考图片
MaaS_KeLing_O1_video：无参考视频+有多图主体时，参考图+多图主体 ≤7；有参考视频+有多图主体时 ≤4

视频（feature_video / base_video）：

格式 .mp4 / .mov；≤200MB；最多 1 段参考视频
时长：MaaS_KeLing_3.0_video-omni 为 3～15.5s；MaaS_KeLing_O1_video 为 3～10s
分辨率：MaaS_KeLing_3.0_video-omni 宽高 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_3.0_video-omni：首帧或首尾帧场景最多 3 主体；无视频+仅多图 ≤7；无视频+仅视频角色 ≤3；无视频+两者时视频角色 ≤3 且图+多图 ≤4；有视频+仅多图 ≤4；有视频+仅视频角色 ≤1；有参考视频时不同时支持视频角色主体和多图主体
MaaS_KeLing_O1_video：仅多图主体；使用首尾帧时不支持主体；无参考视频时图+主体 ≤7，有参考视频时 ≤4

响应 / 示例

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

查询任务（通用协议）

请求 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}

请求 query 参数

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

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

参数名	字段类型	描述
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）时代表积分扣减量；十进制

请求示例

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