主题模式

可灵接口文档 ​

可灵官方文档（可参考）：https://klingai.com/document-api/api/video/3-0-omni/text-to-video

API 总览 ​

统一请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

核心说明 ​

  1. 统一采用 {BASE_URL}/api/v1/multimodal/kling/videos/... 接口路径承载可灵视频能力。

  2. 统一采用 {BASE_URL}/api/v1/multimodal/kling/general/... 接口路径承载可灵主体和音色能力。

  3. 当前视频任务长期可查，但 URL 有有效期，查询到视频结果后请及时转存。

  4. BASE_URL为https://aiping.cn

视频能力接口 ​

1) 文生视频（Text2Video） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/text2video
单任务查询GET/api/v1/multimodal/kling/videos/text2video/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/text2video?pageNum=1&pageSize=30

2) 图生视频（Image2Video） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/image2video
单任务查询GET/api/v1/multimodal/kling/videos/image2video/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/image2video?pageNum=1&pageSize=30

3) Omni / 多镜头（Omni Video） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/omni-video
单任务查询GET/api/v1/multimodal/kling/videos/omni-video/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/omni-video?pageNum=1&pageSize=30

4) 多图参考生视频（Multi-Image2Video） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/multi-image2video
单任务查询GET/api/v1/multimodal/kling/videos/multi-image2video/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/multi-image2video?pageNum=1&pageSize=30

5) 动作控制（Motion Control） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/motion-control
单任务查询GET/api/v1/multimodal/kling/videos/motion-control/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/motion-control?pageNum=1&pageSize=30

6) 视频延长（Video Extend） ​

功能方法路径
创建POST/api/v1/multimodal/kling/videos/video-extend
单任务查询GET/api/v1/multimodal/kling/videos/video-extend/{task_id}
列表查询GET/api/v1/multimodal/kling/videos/video-extend?pageNum=1&pageSize=30

主体能力接口 ​

能力方法路径
创建自定义主体POST/api/v1/multimodal/kling/general/advanced-custom-elements
查询自定义主体列表GET/api/v1/multimodal/kling/general/advanced-custom-elements
查询自定义主体单个GET/api/v1/multimodal/kling/general/advanced-custom-elements/{id}
查询官方主体列表GET/api/v1/multimodal/kling/general/advanced-presets-elements
删除自定义主体POST/api/v1/multimodal/kling/general/delete-elements

音色能力接口 ​

能力方法路径
创建自定义音色POST/api/v1/multimodal/kling/general/custom-voices
查询自定义音色单个GET/api/v1/multimodal/kling/general/custom-voices/{id}
查询自定义音色列表GET/api/v1/multimodal/kling/general/custom-voices?pageNum=1&pageSize=30
查询官方音色列表GET/api/v1/multimodal/kling/general/presets-voices?pageNum=1&pageSize=30
删除自定义音色POST/api/v1/multimodal/kling/general/delete-voices

返回结果（总览） ​

创建任务返回（示例） ​

JSON
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

单任务查询返回（示例） ​

JSON
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

列表查询返回（示例） ​

JSON
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

文生视频 ​

文生视频用于根据文本提示词生成视频。

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/text2videoPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
model_namestring否Kling-V3推荐使用的模型字段，目前支持Kling-V3，Kling-V2.6，Kling-V1.6
modelstring否无兼容字段，会映射到 model_name
promptstring否无文本提示词
negative_promptstring否空负向提示词
multi_shotboolean否false多镜头开关
shot_typestring条件必填无multi_shot=true 时按上游规则生效
multi_promptarray条件必填无多镜头分镜信息
soundstring否off是否生成声音
cfg_scalefloat否0.5提示词参考强度，取值范围 [0,1]
modestring否std视频模式
aspect_ratiostring否16:9画面比例
secondsstring否无兼容时长字段
durationstring否无时长字段
camera_controlobject否空运镜控制
watermark_infoobject否空是否同时生成含水印的结果
callback_urlstring否空回调地址
external_task_idstring否空自定义任务 ID

请求示例 ​

Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/videos/text2video \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
      "model_name": "Kling-V2.6",
      "prompt": "一只可爱的小兔子，戴着眼镜，坐在桌边，看报纸，桌上放着一杯卡布奇诺",
      "negative_prompt": "",
      "duration": "5",
      "mode": "pro",
      "sound": "on",
      "aspect_ratio": "1:1",
      "callback_url": "",
      "external_task_id": ""
    }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/text2video/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

Java
{
  "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天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" // 视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "final_balance_deduction": {
      "quota": "string"
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/text2video?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询任务返回（列表） ​

Java
{
  "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天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" // 视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
    }
  ]
}

注意事项 ​

  1. 参数与取值以官方文档为准，优先使用 model_name。

  2. model 仅是兼容写法，不建议作为主文档字段。

  3. 不同模型在 mode、duration、sound、camera_control 上支持范围不同，以官方能力地图为准。

图生视频 ​

图生视频用于根据参考图像（首帧/尾帧）与提示词生成视频。

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/image2videoPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
model_namestring可选Kling-V3推荐模型字段，目前支持Kling-V3，Kling-V2.6，Kling-V1.6
modelstring可选无兼容字段，会映射到 model_name
imagestring条件必填无参考图，支持 URL/Base64；与 image_tail 至少二选一
image_tailstring条件必填无尾帧参考图；与 image 至少二选一
multi_shotboolean可选false是否多镜头；true 时 prompt 失效
shot_typestring条件必填无multi_shot=true 时必填：customize/intelligence
promptstring条件必填无正向提示词；长度不超过 2500
multi_promptarray条件必填无multi_shot=true 且 shot_type=customize 时必填
negative_promptstring可选空负向提示词，长度不超过 2500
element_listarray可选空参考主体列表，最多 3 个主体
voice_listarray可选空音色列表，最多 2 个，和 element_list 互斥
soundstring可选off是否生成声音：on/off
cfg_scalefloat可选0.5自由度，范围 [0,1]（kling-v2.x 不支持）
modestring可选std生成模式：std / pro / 4k
static_maskstring可选空静态笔刷 mask 图片
dynamic_masksarray可选空动态笔刷配置列表（每项含 mask + trajectories）
camera_controlobject可选空摄像机运动控制参数
aspect_ratiostring可选16:9画面比例：16:9 / 9:16 / 1:1
secondsstring可选无兼容时长字段
durationstring可选无时长字段
watermark_infoobject可选空水印开关
callback_urlstring可选空回调地址
external_task_idstring可选空自定义任务 ID

请求示例 ​

Shell
curl --location --request POST 'https://aiping.cn/api/v1/multimodal/kling/videos/image2video' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "model_name": "Kling-V2.6",
      "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png",
      "image_tail": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
      "prompt": "镜头拉远，女生微笑",
      "negative_prompt": "",
      "duration": "5",
      "mode": "pro",
      "sound": "off",
      "callback_url": "",
      "external_task_id": ""
  }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/image2video/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

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

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/image2video?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询任务返回（列表） ​

Java
{
  "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天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" // 视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
    }
  ]
}

参数兼容 ​

兼容字段行为
model自动映射到官方字段 model_name
seconds统一视频创建流程可兼容，最终按标准化逻辑处理

接口约束 ​

当模型为 Kling-Video-O1 或 Kling-V3-Omni 时，请使用 /api/v1/multimodal/kling/videos/omni-video。

注意事项 ​

  1. 参数与取值以官方文档为准。

  2. 图生视频涉及较多互斥/组合规则（如 element_list 与 voice_list、multi_shot 条件必填等），请按官方约束组包。

多图参考生视频 ​

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/multi-image2videoPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
model_namestring否Kling-V1.6推荐模型字段，目前支持Kling-V1.6
modelstring否无兼容字段，会映射到 model_name
image_listarray是无参考图片列表（会自动归一化）
reference_imagesarray否无image_list 兼容别名
promptstring否空正向提示词
negative_promptstring否空负向提示词
modestring否std模式（常见 std / pro）
secondsstring否无兼容时长字段
durationstring否无时长字段
aspect_ratiostring否16:9画面比例
watermark_infoobject否空水印开关
callback_urlstring否空回调地址
external_task_idstring否空自定义任务 ID

请求示例 ​

Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/videos/multi-image2video \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
      "model_name": "Kling-V1.6",
      "image_list": [
        { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png" },
        { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog_cloth.png" }
      ],
      "prompt": "一只白色比熊穿着东北红色花棉袄，舔自己的手",
      "negative_prompt": "",
      "mode": "pro",
      "duration": "5",
      "aspect_ratio": "16:9",
      "callback_url": "",
      "external_task_id": ""
    }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/multi-image2video/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

Java
{
  "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天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" //视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "final_balance_deduction": {
      "quota": "string"
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/multi-image2video?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询参数 ​

参数名类型必填默认值说明
task_idstring是-任务 ID（单任务查询时路径参数）
pageNumint否1页码，范围 [1, 1000]
pageSizeint否30每页数据量，范围 [1, 500]
providerstring否-指定服务商

查询任务返回（列表） ​

Java
{
  "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天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" //视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

注意事项 ​

  1. model 是兼容字段，建议优先使用 model_name。

  2. 多图输入建议直接按 { "image": "..." } 结构传参，最稳定。

动作控制 ​

动作控制用于通过参考图像和参考视频生成视频，使生成视频中的人物动作与参考视频一致。

创建动作控制任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/motion-controlPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
model_namestring可选Kling-V2.6推荐模型字段，目前支持Kling-V3，Kling-V2.6
modelstring可选无兼容字段，会映射到 model_name
promptstring可选空文本提示词，不超过 2500
image_urlstring必填无参考图像（URL/Base64）
video_urlstring必填无参考视频链接
element_listarray可选空主体参考列表（当前最多 1 个主体）
keep_original_soundstring可选yes是否保留原声：yes/no
character_orientationstring必填无人物朝向：image / video
modestring必填无生成模式：std / pro
watermark_infoobject可选空水印开关，格式：{\"enabled\": boolean}
callback_urlstring可选空回调地址
external_task_idstring可选空自定义任务 ID

请求示例 ​

Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/videos/motion-control \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json; charset=utf-8' \
    --data-raw '{
      "model_name": "Kling-V2.6",
      "image_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png",
      "prompt": "女孩穿着灰色宽松T恤和牛仔短裤",
      "video_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4",
      "keep_original_sound": "yes",
      "character_orientation": "image",
      "mode": "pro",
      "callback_url": "",
      "external_task_id": "xxx"
    }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/motion-control/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

Java
{
  "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天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" //视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "final_balance_deduction": {
      "quota": "string"
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/motion-control?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询任务返回（列表） ​

Java
{
  "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天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" //视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

参数兼容 ​

兼容字段行为
action_control历史兼容字段，当前路径下会在透传前清理，不作为必填

注意事项 ​

  1. 建议优先使用 model_name，model 为兼容写法。

  2. action_control 不是当前主参数，仅为历史兼容字段。

  3. mode 在官方动作控制接口口径下为 std/pro，请避免传入不受支持模式。

Omni 视频生成 ​

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/omni-videoPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
model_namestring否上游默认推荐模型字段，目前支持kling-video-o1 ， kling-v3-omni
modelstring否无兼容字段，会映射到 model_name
multi_shotboolean否false是否多镜头，kling-video-o1 不支持分镜
shot_typestring条件必填无multi_shot=true 时生效
promptstring条件必填无提示词（单镜头或智能分镜必填）
multi_promptarray条件必填无multi_shot=true 且 shot_type=customize 时必填
image_listarray否空参考图列表（可含首尾帧）
element_listarray否空主体参考列表
video_listarray否空参考视频列表（refer_type=base/feature）
soundstring否off是否生成声音
modestring否pro模式（std/pro/4k）
aspect_ratiostring否无画幅（16:9/9:16/1:1）
secondsstring否无兼容时长字段
durationstring否无时长字段
watermark_infoobject否空水印开关
callback_urlstring否空回调地址
external_task_idstring否空自定义任务 ID

请求示例 ​

普通参考图： ​
Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/videos/omni-video \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
    "model_name": "Kling-Video-O1",
    "prompt": "让<<<image_1>>>中的人物向镜头挥手",
    "image_list": [
      {
        "image_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png"
      }
    ],
    "duration": "5",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "callback_url": "",
    "external_task_id": ""
  }'
首尾帧： ​
Shell
curl --location 'https://aiping.cn/api/v1/multimodal/kling/videos/omni-video' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
      "model_name": "Kling-Video-O1",
      "prompt": "视频中的人跳舞",
      "image_list": [
        {
            "image_url": "xxx",
          "type": "first_frame"
        },
        {
            "image_url": "xxx",
          "type": "end_frame"
        }
      ],
      "mode": "pro"
  }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/omni-video/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

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

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/omni-video?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询任务返回（列表） ​

Java
{
  "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_id两种查询方式二选一）
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // 生成的视频ID，全局唯一
            "url": "string", // 生成视频的URL，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" //视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

关键约束 ​

  1. 多镜头开启时，shot_type 与 multi_prompt 需满足组合规则。

  2. 有 video_list 且 refer_type=base 时，上游 Omni 会按"视频编辑/指令变换"场景处理，请求路径仍为 /api/v1/multimodal/kling/videos/omni-video，但时长/比例等参数会受到视频编辑场景限制。

  3. Kling-Video-O1、Kling-V3-Omni 应优先走本路径，若走 text2video/image2video 路径可能返回 422。

视频延长 ​

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/video-extendPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

参数名类型必填默认值说明
video_idstring必填无视频 ID，支持通过文本、图片和视频延长生成的视频 ID（原视频不能超过 3 分钟），仅支持 V1.6 模型生成的视频
promptstring可选空文本提示词，不超过 2500
negative_promptstring可选空负向文本提示词，不超过 2500
cfg_scalefloat可选0.5提示词参考强度，数值越大参考强度越大，取值范围：[0, 1]
watermark_infoobject可选空水印开关，格式：{\"enabled\": boolean}
callback_urlstring可选空回调地址
external_task_idstring可选空自定义任务 ID

请求示例 ​

Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/videos/video-extend \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
      "prompt": "出现一只小狗",
      "video_id": "743211632612511839",
      "negative_prompt": "",
      "callback_url": ""
    }'

创建返回 ​

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

查询任务 ​

查询单个 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/video-extend/{task_id}GETapplication/jsonapplication/json

查询任务返回（单个） ​

Java
{
  "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": { //任务创建时的参数信息
      "parent_video": {
        "id": "string", //续写前的视频ID，全局唯一
        "url": "string", //续写前视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
        "duration": "string" //续写前的视频总时长，单位s
      },
      "external_task_id": "string"//客户自定义任务ID
    },
    "task_result": {
      "videos": [ //数组是为了保留扩展性，以防未来要支持n
        {
          "id": "string", //续写后的完整视频ID，全局唯一
          "url": "string", //续写后视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" //视频总时长，单位s（秒）
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "final_balance_deduction": {
      "quota": "string"
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询列表 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/videos/video-extend?pageNum=1&pageSize=30GETapplication/jsonapplication/json

查询任务返回（列表） ​

Java
{
  "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": { //任务创建时的参数信息
        "parent_video": {
          "id": "string", //续写前的视频ID，全局唯一
          "url": "string", //续写前视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
          "duration": "string" //续写前的视频总时长，单位s
        },
        "external_task_id": "string"//客户自定义任务ID
      },
      "task_result": {
        "videos": [ //数组是为了保留扩展性，以防未来要支持n
          {
            "id": "string", //续写后的完整视频ID，全局唯一
            "url": "string", //续写后视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" //视频总时长，单位s（秒）
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

主体管理 ​

重要约定 ​

  1. 主体 ID：创建成功后返回主体唯一标识 element_id，后续查询、视频生成、删除均使用该 ID。

  2. 异步状态：status 枚举为 submitted（已提交）、 processing（处理中）、succeed（成功）、failed（失败）。创建后通常为 processing 或 submitted，需轮询查询单个接口，后台也会自动收敛状态。

  3. 可用时机：仅当 status = succeed 后，该主体才可用于视频生成。

  4. aiping_id：返回会同时返回相同值 request_id 和 aiping_id，当出现错误时提供 request_id 和 aiping_id用来排查具体错误。

创建主体 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/advanced-custom-elementsPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息，参考接口鉴权

请求体参数 ​

字段类型必填默认值描述
element_namestring必填无主体名称，不能超过 20 个字符
element_descriptionstring必填无主体描述，不能超过 100 个字符
reference_typestring必填无主体参考方式，枚举：image_refer（多图主体）、video_refer（视频角色主体）
element_image_listobject条件必填无reference_type=image_refer 时必填。含 1 张正面参考图与 1~3 张其他参考图
element_video_listobject条件必填无reference_type=video_refer 时必填。至多 1 段视频，含人声时触发音色定制
element_voice_idstring可选无绑定音色库中已有音色 ID
tag_listarray可选无主体标签列表，如 [{"tag_id":"o_102"}]
external_task_idstring可选无自定义任务 ID（单用户内需唯一）
callback_urlstring可选无任务结果回调地址（透传可灵）
element_image_list 结构 ​
JSON
"element_image_list": {
  "frontal_image": "image_url_0",
  "refer_images": [{ "image_url": "image_url_1" }]
}
  • 支持图片 URL 或 Base64，格式 .jpg/.jpeg/.png，大小 ≤ 10MB，宽高 ≥ 300px，宽高比在 1:2.5 ~ 2.5:1。
element_video_list 结构 ​
JSON
"element_video_list": {
  "refer_videos": [{ "video_url": "video_url_1" }]
}

  • 视频格式 MP4/MOV，时长 3s~8s，宽高比 16:9 或 9:16 的 1080P，至多 1 段，大小 ≤ 200MB。

  • 视频定制的主体仅支持用于 kling-video-o3 及之后的模型。

请求示例（图片定制） ​

Bash
curl -sS -X POST \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/multimodal/kling/general/advanced-custom-elements" \
  -d '{
    "element_name": "测试主体",
    "element_description": "这是一个测试主体描述",
    "reference_type": "image_refer",
    "element_image_list": {
      "frontal_image": "https://example.com/image0.jpg",
      "refer_images": [
        { "image_url": "https://example.com/image1.jpg" },
        { "image_url": "https://example.com/image2.jpg" }
      ]
    },
    "tag_list": [{ "tag_id": "o_102" }]
  }'

创建返回 ​

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

task_id 为后续查询/使用的统一主体 ID，status=submitted 表示已经提交请求，后续需轮询查询单个接口。

查询自定义主体（单个） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/advanced-custom-elements/{id}GETapplication/jsonapplication/json

请求头 ​

字段值描述
AuthorizationBearer鉴权信息

路径参数 ​

字段类型必填默认值描述
task_idstring必填无主体 ID（创建时返回的 task_id）。
external_task_idstring可选无自定义任务 id

用户自定义任务 ID

  • 创建任务时填入的 external_task_id，与 task_id 两种查询方式二选一
  • 请注意，单用户下需要保证唯一性

请求示例 ​

Bash
curl -sS \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/multimodal/kling/general/advanced-custom-elements/{id}"

查询返回（请求成功） ​

JSON
{
  "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": {
      "elements": [
        {
          "element_id": 0, //主体ID
          "element_name": "string", //主体名称
          "element_description": "string", //主体描述
          "reference_type": "video_refer", //参考方式
          "element_image_list": {},
          "element_video_list": {},
          "element_voice_info": {
            "voice_id": "string", //定制的音色的ID，全局唯一
            "voice_name": "string", //定制的音色的名称
            "trial_url": "string", //定制的音色的试听音频下载URL
            "owned_by": "kling" //音色来源
          },
          "tag_list": [],
          "owned_by": "kling", //主体来源
          "status": "succeed" //主体状态，正常时为succeed，已被删除时为 deleted
        }
      ]
    },
    "final_unit_deduction": "string", //任务最终扣减积分数值
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

  • status=failed 时，data.error_message 给出失败原因（如触发内容风控）。

  • final_unit_deduction为扣费部分，详细见 计费说明

查询自定义主体（列表） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/advanced-custom-elementsGETapplication/jsonapplication/json

查询参数 ​

字段类型必填默认值描述
pageNumint可选1页码，取值范围 [1, 1000]
pageSizeint可选20每页数据量，取值范围 [1, 500]

查询返回 ​

JSON
{
  "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": {
        "elements": [
          {
            "element_id": 0,
            "element_name": "string",
            "element_description": "string",
            "reference_type": "video_refer",
            "element_image_list": {},
            "element_video_list": {},
            "element_voice_info": {},
            "tag_list": [],
            "owned_by": "kling", //主体来源
            "status": "succeed" //主体状态，正常时为succeed，已被删除时为 deleted
          }
        ]
      },
      "final_unit_deduction": "string", //任务最终扣减积分数值
      "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

  • final_unit_deduction为扣费部分，详细见 计费说明。

  • 成功、失败，以及被删除的主体都会在响应中展示。

查询官方主体（列表） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/advanced-presets-elementsGETapplication/jsonapplication/json

查询参数 ​

字段类型必填默认值描述
pageNumint可选1页码，取值范围 [1, 1000]
pageSizeint可选20每页数据量，取值范围 [1, 500]

查询返回 ​

JSON
{
  "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": {
        "elements": [
          {
            "element_id": 0,
            "element_name": "string",
            "element_description": "string",
            "reference_type": "video_refer",
            "element_image_list": {},
            "element_video_list": {},
            "element_voice_info": {},
            "tag_list": [],
            "owned_by": "kling", //主体来源
            "status": "succeed" //主体状态，正常时为succeed，已被删除时为 deleted
          }
        ]
      },
      "final_unit_deduction": "string", //任务最终扣减积分数值
      "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
    }
  ]
}

删除主体 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/delete-elementsPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

字段类型必填默认值描述
element_idstring必填无要删除的主体 ID（创建时返回的 element_id）。非本人主体返回 404

请求示例 ​

Bash
curl -sS -X POST \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/multimodal/kling/general/delete-elements" \
  -d '{ "element_id": "{YOUR_ELEMENT_ID}" }'

删除返回 ​

JSON
{
  "code": 0, //错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", //任务ID
    "task_status": "string" //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
  }
}

删除主体时不会返回task_id，不过删除主体后，可以用原来创建该主体时的taskid查到该主体，返回信息中有"status": "deleted"，表示该主体已被删除

音色管理 ​

创建自定义音色 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/custom-voicesPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

字段类型必填默认值描述
voice_namestring是无音色名称：文本内容最大长度 20 个字符，创建后不再使用的音色可以通过 API 删除
voice_urlstring否无音色数据文件获取 URL。支持 .mp3 / .wav / .mp4 / .mov 格式的音视频文件，音频中人声需干净无杂音，且只能有一种人声，时长不短于 5 秒且不长于 30 秒
video_idstring否无历史作品 ID，可通过引用历史作品提供音频素材。仅满足以下条件的视频可以用于定制音色：1. 使用 V2.6 版本模型生成且开启 sound 参数值为 on 的视频；2. 通过数字人 API 生成的视频；3. 通过对口型 API 生成的视频。音频中人声需干净无杂音，且只能有一种人声，时长不短于 5 秒且不长于 30 秒。
external_task_idstring否无自定义任务 ID。传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询，请注意，单用户下需要保证唯一性。
callback_urlstring否无本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。

请求示例 ​

Shell
curl --location --request POST 'https://aiping.cn/api/v1/multimodal/kling/general/custom-voices' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "video_id": "",
    "voice_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/out.mp3",
    "voice_name": "定制人声",
    "callback_url": ""
  }'

创建任务返回示例 ​

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

task_status=submitted/processing 时表示音色仍在处理，需轮询查询单个接口。

查询自定义音色（单个） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/custom-voices/{id}GETapplication/jsonapplication/json

请求头 ​

字段值描述
AuthorizationBearer鉴权信息

请求体参数 ​

字段类型必填默认值描述
task_idstring是无创建音色返回的任务 ID
external_task_idstring否无使用自定义任务 ID 查询，创建任务时填入的 external_task_id，与 task_id 两种查询方式二选一

查询任务返回示例（单个） ​

JSON
{
  "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": {
      "voices": [
        {
          "voice_id": "string", // 定制的音色的ID，全局唯一
          "voice_name": "string", // 定制的音色的名称
          "trial_url": "string", // 定制的音色的试听音频下载URL
          "owned_by": "kling" // 音色来源
        }
      ]
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "final_balance_deduction": {
      "quota": "string"
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

查询自定义音色（列表） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/custom-voicesGETapplication/jsonapplication/json

请求头 ​

字段值描述
AuthorizationBearer鉴权信息

查询参数 ​

字段类型必填默认值描述
pageNumint否1页码，取值范围 [1, 1000]
pageSizeint否20每页数据量，取值范围 [1, 1000]

查询任务返回示例（列表） ​

JSON
{
  "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": {
        "voices": [
          {
            "voice_id": "string", // 定制的声音的ID，全局唯一
            "voice_name": "string", // 定制的音色的名称
            "trial_url": "string", // 定制的音色的试听音频下载URL
            "owned_by": "kling" // 音色来源
          }
        ]
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "final_balance_deduction": {
        "quota": "string"
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
    }
  ]
}

查询官方音色（列表） ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/presets-voicesGETapplication/jsonapplication/json

注意：有两个官方音色不满 5s，不可用

voice_nametrial_url
视频原声https://v4-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/740716864409964585/AUDIO/20260604/83c96e92f9e5d337f4059d7b81c53567-f1198a4d-2fe9-4d63-b632-818a20892cfc.quality.wav?x-kcdn-pid=112452
播报男声https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/740716864409964585/AUDIO/20251216/3052fac5c1458a414bd8d8268c6bac7d-bfbcfbe4-74ab-4be5-9f89-168506e5c227.quality.wav?x-kcdn-pid=112452

请求头 ​

字段值描述
AuthorizationBearer鉴权信息

查询参数 ​

字段类型必填默认值描述
pageNumint否1页码，取值范围 [1, 1000]
pageSizeint否20每页数据量，取值范围 [1, 1000]

官方音色返回示例 ​

JSON
{
  "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_result": {
        "voices": [
          {
            "voice_id": "string", // 系统预置的音色的ID，全局唯一
            "voice_name": "string", // 系统预置的音色的名称
            "trial_url": "string", // 系统预置的音色的试听音频下载URL
            "owned_by": "kling" // 音色来源
          }
        ]
      },
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
    }
  ]
}

删除自定义音色 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/general/delete-voicesPOSTapplication/jsonapplication/json

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

请求体参数 ​

字段类型必填默认值描述
voice_idstring必填无要删除的音色 ID，仅支持删除自定义音色

请求示例 ​

Shell
curl --location --request POST 'https://aiping.cn/api/v1/multimodal/kling/general/delete-voices' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "voice_id":""
}'

删除返回示例 ​

JSON
{
  "code": 0, // 错误码，
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_status": "string" // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
  }
}

计费说明 ​

自定义音色创建成功后会进行计费，计费模块名为 custom-voices。

调用记录金额会以 custom-voices 作为模块名展示计费信息