Skip to content

可灵 4.0 视频生成接口文档(新版) ​

可灵官方文档(可参考):https://klingai.com/document-api/api/video/4-0/text-to-video

本文文生视频、图生视频、Omni 视频生成及任务查询、列表适用于模型 Kling-4.0 与 Kling-4.0-Flash。

API 总览 ​

统一请求头 ​

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

核心说明 ​

  1. 文生视频、图生视频与 Omni 视频生成采用 {BASE_URL}/api/v1/multimodal/kling/{能力}/{model} 接口路径。

  2. 统一采用 {BASE_URL}/api/v1/multimodal/kling/tasks 接口查询视频任务与列表。

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

  4. BASE_URL为https://aiping.cn

视频能力接口 ​

1) 文生视频(Text2Video) ​

功能方法路径
创建POST/api/v1/multimodal/kling/text-to-video/{model}
查询任务(通过任务 ID)GET/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}
查询任务(通过游标)POST/api/v1/multimodal/kling/tasks

2) 图生视频(Image2Video) ​

功能方法路径
创建POST/api/v1/multimodal/kling/image-to-video/{model}
查询任务(通过任务 ID)GET/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}
查询任务(通过游标)POST/api/v1/multimodal/kling/tasks

3) Omni / 全能参考(Omni Video) ​

功能方法路径
创建POST/api/v1/multimodal/kling/omni-video/{model}
查询任务(通过任务 ID)GET/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}
查询任务(通过游标)POST/api/v1/multimodal/kling/tasks

返回结构(总览) ​

以下返回适用于文生视频、图生视频与 Omni 视频生成。

创建任务返回(示例) ​

JSON
{
  "code": 0,
  "message": "string",
  "data": {
    "id": "string",
    "status": "submitted",
    "external_id": "string",
    "create_time": 1722769557708,
    "update_time": 1722769557708
  }
}

查询任务返回(通过任务 ID,示例) ​

JSON
{
  "code": 0,
  "message": "SUCCEED",
  "data": [
    {
      "id": "string",
      "status": "succeeded",
      "message": "string",
      "external_id": "string",
      "outputs": [
        {
          "type": "video",
          "id": "string",
          "url": "string",
          "duration": "string"
        }
      ],
      "usage": {
        "output_duration": "5"
      },
      "billing": [
        {
          "charge_type": "cash",
          "amount": "string",
          "list_price": "string"
        }
      ],
      "create_time": 1722769557708,
      "update_time": 1722769557708
    }
  ]
}

查询任务返回(通过游标,示例) ​

JSON
{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "result": [
      {
        "id": "string",
        "status": "succeeded",
        "message": "string",
        "external_id": "string",
        "outputs": [
          {
            "type": "video",
            "id": "string",
            "url": "string",
            "duration": "string"
          }
        ],
        "usage": {
          "output_duration": "5"
        },
        "billing": [
          {
            "charge_type": "cash",
            "amount": "string",
            "list_price": "string"
          }
        ],
        "create_time": 1722769557708,
        "update_time": 1722769557708
      }
    ],
    "count": 1,
    "next_cursor": "",
    "has_more": false
  }
}

文生视频 ​

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/text-to-video/{model}POSTapplication/jsonapplication/json

请求体参数 ​

参数名类型必填默认值说明
promptstring是无文本提示词,可包含正向和负向描述
settingsobject否空视频生成配置
settings.resolutionstring否依模型Kling 4.0 支持 720p、1080p,默认 1080p;Kling 4.0 Flash 仅支持 720p,默认 720p
settings.aspect_ratiostring否16:9画面比例:21:9、16:9、9:16、1:1、4:3、3:4
settings.durationinteger否见说明时长字段,单位秒;Kling 4.0 支持 3–30,Kling 4.0 Flash 支持 3–20。指定值优先于提示词时长;未指定时按提示词中的明确时长,否则默认 10 秒
optionsobject否空通用任务配置
options.watermark_infoobject否空是否同时生成含水印的结果
options.watermark_info.enabledboolean否false水印开关,不支持自定义水印
options.callback_urlstring否空回调地址
options.external_task_idstring否空自定义任务 ID,账号内唯一,不超过 80 字节

请求示例 ​

Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/text-to-video/{model} \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
      "prompt": "一只可爱的小兔子,戴着眼镜,坐在桌边,看报纸,桌上放着一杯卡布奇诺",
      "settings": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "1:1"
      },
      "options": {
        "callback_url": "",
        "external_task_id": ""
      }
    }'

创建返回 ​

JSON
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "string", // 错误信息
  "data": {
    "id": "string", // 任务ID,系统生成
    "external_id": "string", // 自定义任务ID
    "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
    "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
    "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
  }
}

查询任务 ​

查询任务(通过任务 ID) ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}GETapplication/jsonapplication/json
参数名类型必填默认值说明
task_idsstring条件必填无系统生成的任务 ID;多个 ID 使用英文逗号分隔
external_task_idsstring条件必填无自定义任务 ID;多个 ID 使用英文逗号分隔

使用 task_ids 查询任务 ID,或使用 external_task_ids 查询自定义任务 ID,两种查询方式二选一。

查询任务返回(通过任务 ID) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 错误信息
  "data": [
    {
      "id": "string", // 任务ID,系统生成
      "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
      "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
      "external_id": "string", // 自定义任务ID
      "outputs": [
        {
          "type": "video", // 生成结果类型
          "id": "string", // 生成的视频ID;全局唯一
          "url": "string", // 生成视频的URL
          "watermark_url": "string", // 含水印视频下载URL,防盗链格式
          "duration": "string" // 视频总时长,单位s
        }
      ],
      "usage": {
        "output_duration": "string" // 输出视频计费用时长,单位s
      },
      "billing": [
        {
          "charge_type": "string", // 扣费账户类型:cash(额度)、unit(资源包)
          "amount": "string", // 扣减数值
          "list_price": "string" // 额度扣减刊例价
        }
      ],
      "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
      "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
    }
  ]
}

查询任务(通过游标) ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/tasksPOSTapplication/jsonapplication/json
参数名类型必填默认值说明
start_timestring否end_time 前 30 天任务创建时间起点,Unix 毫秒时间戳字符串;必须早于 end_time
end_timestring否当前时间任务创建时间终点,Unix 毫秒时间戳字符串
cursorstring否空上一页返回的 next_cursor,首屏不传
limitinteger否100每页数量,取值范围 1–500
filtersarray否空筛选条件
filters[].keystring否无筛选字段:status、product_type
filters[].valuesarray of string否无status:submitted、processing、succeeded、failed;product_type:video、image、try_on

查询任务返回(通过游标) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 错误信息
  "data": {
    "result": [
      {
        "id": "string", // 任务ID,系统生成
        "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
        "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
        "external_id": "string", // 自定义任务ID
        "outputs": [
          {
            "type": "video", // 生成结果类型
            "id": "string", // 生成的视频ID;全局唯一
            "url": "string", // 生成视频的URL
            "watermark_url": "string", // 含水印视频下载URL,防盗链格式
            "duration": "string" // 视频总时长,单位s
          }
        ],
        "usage": {
          "output_duration": "string" // 输出视频计费用时长,单位s
        },
        "billing": [
          {
            "charge_type": "string", // 扣费账户类型:cash(额度)、unit(资源包)
            "amount": "string", // 扣减数值
            "list_price": "string" // 额度扣减刊例价
          }
        ],
        "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
        "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
      }
    ],
    "count": 1, // 本页返回数量
    "next_cursor": "string", // 查询后续结果的游标
    "has_more": true // 是否还有后续结果
  }
}

注意事项 ​

  1. 参数与取值以官方文档为准,模型由 URL 中的 {model} 指定,使用 AIPing 模型页的调用名。

  2. 不同模型在 settings.resolution、settings.duration 上支持范围不同,以官方能力地图为准。

图生视频 ​

创建任务 ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/image-to-video/{model}POSTapplication/jsonapplication/json

请求体参数 ​

参数名类型必填默认值说明
contentsarray是无提示词与参考图列表
contents[].typestring是无输入类型:Kling 4.0 支持 prompt、first_frame、middle_frame、last_frame;Kling 4.0 Flash 仅支持 prompt、first_frame
contents[].textstring条件必填无type=prompt 时必填,文本提示词
contents[].urlstring条件必填无图片输入时必填,支持 URL/Base64;JPG、JPEG、PNG,单张不超过 30 MB,宽高均不少于 300 px,宽高比 2:5 至 5:2
contents[].idstring可选无Kling 4.0 图片的引用 ID,任务内唯一,可在提示词中用 @id 引用;Flash 图生无需此字段
settingsobject可选空视频生成配置
settings.resolutionstring可选依模型Kling 4.0 支持 720p、1080p,默认 1080p;Kling 4.0 Flash 仅支持 720p,默认 720p
settings.durationinteger可选见说明时长字段,单位秒;Kling 4.0 支持 3–30,Kling 4.0 Flash 支持 3–20。指定值优先于提示词时长;未指定时按提示词中的明确时长,否则默认 10 秒
optionsobject可选空通用任务配置
options.watermark_infoobject可选空是否同时生成含水印的结果
options.watermark_info.enabledboolean可选false水印开关,不支持自定义水印
options.callback_urlstring可选空回调地址
options.external_task_idstring可选空自定义任务 ID,账号内唯一,不超过 80 字节

请求示例 ​

Shell
curl --location --request POST 'https://aiping.cn/api/v1/multimodal/kling/image-to-video/{model}' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "contents": [
        {
          "type": "first_frame",
          "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png"
        },
        {
          "type": "last_frame",
          "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png"
        },
        {
          "type": "prompt",
          "text": "镜头拉远,女生微笑"
        }
      ],
      "settings": {
        "duration": 5,
        "resolution": "720p"
      },
      "options": {
        "callback_url": "",
        "external_task_id": ""
      }
  }'

创建返回 ​

JSON
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "string", // 错误信息
  "data": {
    "id": "string", // 任务ID,系统生成
    "external_id": "string", // 自定义任务ID
    "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
    "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
    "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
  }
}

查询任务 ​

查询任务(通过任务 ID) ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}GETapplication/jsonapplication/json
参数名类型必填默认值说明
task_idsstring条件必填无系统生成的任务 ID;多个 ID 使用英文逗号分隔
external_task_idsstring条件必填无自定义任务 ID;多个 ID 使用英文逗号分隔

使用 task_ids 查询任务 ID,或使用 external_task_ids 查询自定义任务 ID,两种查询方式二选一。

查询任务返回(通过任务 ID) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 错误信息
  "data": [
    {
      "id": "string", // 任务ID,系统生成
      "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
      "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
      "external_id": "string", // 自定义任务ID
      "outputs": [
        {
          "type": "video", // 生成结果类型
          "id": "string", // 生成的视频ID;全局唯一
          "url": "string", // 生成视频的URL
          "watermark_url": "string", // 含水印视频下载URL,防盗链格式
          "duration": "string" // 视频总时长,单位s
        }
      ],
      "usage": {
        "output_duration": "string" // 输出视频计费用时长,单位s
      },
      "billing": [
        {
          "charge_type": "string", // 扣费账户类型:cash(额度)、unit(资源包)
          "amount": "string", // 扣减数值
          "list_price": "string" // 额度扣减刊例价
        }
      ],
      "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
      "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
    }
  ]
}

查询任务(通过游标) ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/tasksPOSTapplication/jsonapplication/json
参数名类型必填默认值说明
start_timestring否end_time 前 30 天任务创建时间起点,Unix 毫秒时间戳字符串;必须早于 end_time
end_timestring否当前时间任务创建时间终点,Unix 毫秒时间戳字符串
cursorstring否空上一页返回的 next_cursor,首屏不传
limitinteger否100每页数量,取值范围 1–500
filtersarray否空筛选条件
filters[].keystring否无筛选字段:status、product_type
filters[].valuesarray of string否无status:submitted、processing、succeeded、failed;product_type:video、image、try_on

查询任务返回(通过游标) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 错误信息
  "data": {
    "result": [
      {
        "id": "string", // 任务ID,系统生成
        "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
        "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
        "external_id": "string", // 自定义任务ID
        "outputs": [
          {
            "type": "video", // 生成结果类型
            "id": "string", // 生成的视频ID;全局唯一
            "url": "string", // 生成视频的URL
            "watermark_url": "string", // 含水印视频下载URL,防盗链格式
            "duration": "string" // 视频总时长,单位s
          }
        ],
        "usage": {
          "output_duration": "string" // 输出视频计费用时长,单位s
        },
        "billing": [
          {
            "charge_type": "string", // 扣费账户类型:cash(额度)、unit(资源包)
            "amount": "string", // 扣减数值
            "list_price": "string" // 额度扣减刊例价
          }
        ],
        "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
        "update_time": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
      }
    ],
    "count": 1, // 本页返回数量
    "next_cursor": "string", // 查询后续结果的游标
    "has_more": true // 是否还有后续结果
  }
}

接口约束 ​

当需要参考视频、主体或音色时,请使用 /api/v1/multimodal/kling/omni-video/{model}。

注意事项 ​

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

  2. 图生视频涉及较多互斥/组合规则(如 Kling 4.0 最多 10 张关键帧,Kling 4.0 Flash 仅支持首帧等),请按官方约束组包。

  3. 请求示例适用于 Kling 4.0;使用 Flash 时删除尾帧项。Kling 4.0 的首帧、中间帧、尾帧按出现顺序排列,多张中间帧同样按顺序排列,建议通过 @id 在提示词中说明各帧作用。

Omni 全能参考生视频 ​

创建任务 ​

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

请求体参数 ​

参数名类型必填默认值说明
contentsarray是无提示词与参考素材列表
contents[].typestring是无prompt、first_frame、refer_image、element、feature_video、base_video;Kling 4.0 另支持 middle_frame、last_frame、voice
contents[].textstring条件必填无type=prompt 时填写提示词;纯英文最多 26,000 字符,纯非英文最多 11,000 字符;混合输入满足 E / 26000 + N / 11000 <= 1,E、N 分别为英文、非英文字符数
contents[].urlstring条件必填无图片或视频地址;图片支持 URL/Base64,视频使用 URL
contents[].element_idstring条件必填无type=element 时填写平台主体 ID,管理接口见主体与音色管理
contents[].voice_idstring条件必填无type=voice 时填写平台音色 ID,仅 Kling 4.0 支持;管理接口见主体与音色管理
contents[].idstring条件必填无本次请求内唯一的素材引用 ID,在提示词中用 @id 引用;主体、音色必填;Kling 4.0 同时传多个 middle_frame 或 refer_image 时必填
settingsobject否空生成配置
settings.audiostring否native音频模式:native 生成音频,original 保留输入视频原音
settings.resolutionstring否按模型Kling 4.0 支持 720p/1080p,默认 1080p;Flash 仅支持 720p,默认 720p
settings.aspect_ratiostring否adaptive画幅(21:9/16:9/9:16/1:1/4:3/3:4/adaptive)
settings.durationinteger否按输入确定时长,单位秒;Kling 4.0 为 3–30,Flash 为 3–20。未指定时依次采用提示词时长、待编辑视频时长四舍五入值、默认 10 秒
optionsobject否空任务选项
options.watermark_infoobject否空水印开关,enabled 默认 false;不支持自定义水印
options.callback_urlstring否空回调地址
options.external_task_idstring否空自定义任务 ID,单用户内唯一,不超过 80 字节

请求示例 ​

普通参考图: ​
Shell
curl --request POST \
    --url https://aiping.cn/api/v1/multimodal/kling/omni-video/{model} \
    --header 'Authorization: Bearer {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
    "contents": [
      {
        "type": "prompt",
        "text": "让@image_1中的人物向镜头挥手"
      },
      {
        "type": "refer_image",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
        "id": "image_1"
      }
    ],
    "settings": {
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    },
    "options": {
      "callback_url": "",
      "external_task_id": ""
    }
  }'
首尾帧: ​
Shell
curl --location 'https://aiping.cn/api/v1/multimodal/kling/omni-video/{model}' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
      "contents": [
        {
          "type": "prompt",
          "text": "视频中的人跳舞"
        },
        {
            "url": "xxx",
          "type": "first_frame"
        },
        {
            "url": "xxx",
          "type": "last_frame"
        }
      ]
  }'

创建返回 ​

JSON
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "string", // 错误信息
  "data": {
    "id": "string", // 任务ID,系统生成
    "external_id": "string", //自定义任务ID,创建时填写后返回
    "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
    "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
    "update_time": 1722769557708 //任务更新时间,Unix时间戳、单位ms
  }
}

查询任务 ​

查询任务(通过任务 ID) ​

网络协议请求地址请求方法请求格式响应格式
https/api/v1/multimodal/kling/tasks?task_ids={task_id_1},{task_id_2}GETapplication/jsonapplication/json

使用 task_ids 查询任务 ID,或使用 external_task_ids 查询自定义任务 ID,两种查询方式二选一。

查询任务返回(通过任务 ID) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 响应信息
  "data": [
    {
      "id": "string", // 任务ID,系统生成
      "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
      "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
      "outputs": [
        {
          "type": "video", // 产物类型
          "id": "string", // 生成的视频ID;全局唯一
          "url": "string", // 生成视频的URL,请及时转存
          "duration": "string" //视频总时长,单位s
        }
      ],
      "external_id": "string", //自定义任务ID,创建时填写后返回
      "usage": { // 任务用量信息
        "input_duration": "5.00", // 有视频输入时返回,归一化后计费用时长,单位s,字符串
        "output_duration": "5" // 输出视频计费用时长,单位s,字符串
      },
      "billing": [
        {
          "charge_type": "cash", // 计费类型
          "amount": "string", // 额度扣减金额
          "list_price": "string" // 额度扣减刊例价
        }
      ],
      "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
      "update_time": 1722769557708 //任务更新时间,Unix时间戳、单位ms
    }
  ]
}

查询任务(通过游标) ​

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

查询任务返回(通过游标) ​

Java
{
  "code": 0, // 错误码;具体定义见错误码
  "message": "SUCCEED", // 响应信息
  "data": {
    "result": [
      {
        "id": "string", // 任务ID,系统生成
        "status": "string", // 任务状态,枚举值:submitted(已提交)、processing(处理中)、succeeded(成功)、failed(失败)
        "message": "string", // 任务状态信息,当任务失败时展示失败原因(如触发平台的内容风控等)
        "external_id": "string", //任务ID,自定义生成,与task_ids两种查询方式二选一
        "outputs": [
          {
            "type": "video", // 产物类型
            "id": "string", // 生成的视频ID;全局唯一
            "url": "string", // 生成视频的URL,请及时转存
            "duration": "string" //视频总时长,单位s
          }
        ],
        "usage": { // 任务用量信息
          "input_duration": "5.00", // 有视频输入时返回,归一化后计费用时长,单位s,字符串
          "output_duration": "5" // 输出视频计费用时长,单位s,字符串
        },
        "billing": [
          {
            "charge_type": "cash", // 计费类型
            "amount": "string", // 额度扣减金额
            "list_price": "string" // 额度扣减刊例价
          }
        ],
        "create_time": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
        "update_time": 1722769557708 //任务更新时间,Unix时间戳、单位ms
      }
    ],
    "count": 1, // 本页返回任务数量
    "next_cursor": "string", // 下一页游标
    "has_more": true // 是否还有下一页
  }
}