Skip to content

可灵主体与音色管理接口文档 ​

本文为主体与音色管理的共用接口文档,配套以下两版生视频接口使用:

API 总览 ​

统一请求头 ​

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

核心说明 ​

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

  2. BASE_URL为https://aiping.cn

扣费字段说明 ​

可灵上游计费已从「资源包积分扣减」切换为「账户余额额度抵扣」。查询任务返回中与扣费相关的字段如下:

字段说明
final_unit_deduction积分体系字段,任务最终扣减积分数值。存量资源包未耗尽期间仍可能返回
final_balance_deduction额度体系字段,额度扣减信息
final_balance_deduction.quota额度扣减折扣价。通过本平台调用时,该值与刊例价一致
final_balance_deduction.list_price额度扣减刊例价(原价)

过渡期两套字段并存,请以接口实际返回为准。

主体能力接口 ​

能力方法路径
创建自定义主体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

在两版生视频接口中使用 ​

生视频版本引用方式
新版Omni 的 contents 中使用 type=element / type=voice,分别填写 element_id / voice_id;voice 仅 Kling-4.0 支持
旧版按具体视频接口的参数定义,使用 element_list / voice_list

主体管理 ​

重要约定 ​

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

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

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

创建主体 ​

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

请求体参数 ​

字段类型必填默认值描述
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

路径参数 ​

字段类型必填默认值描述
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", //任务最终扣减积分数值
    "final_balance_deduction": { // 额度扣减信息
      "quota": "string", // 额度扣减折扣价
      "list_price": "string" // 额度扣减刊例价
    },
    "created_at": 1722769557708, //任务创建时间,Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间,Unix时间戳、单位ms
  }
}
  • status=failed 时,data.error_message 给出失败原因(如触发内容风控)。

  • final_unit_deduction、final_balance_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", //任务最终扣减积分数值
      "final_balance_deduction": { // 额度扣减信息
        "quota": "string", // 额度扣减折扣价
        "list_price": "string" // 额度扣减刊例价
      },
      "created_at": 1722769557708, //任务创建时间,Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间,Unix时间戳、单位ms
    }
  ]
}
  • final_unit_deduction、final_balance_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
          }
        ]
      },
      "created_at": 1722769557708, //任务创建时间,Unix时间戳、单位ms
      "updated_at": 1722769557708 //任务更新时间,Unix时间戳、单位ms
    }
  ]
}

删除主体 ​

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

请求体参数 ​

字段类型必填默认值描述
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

请求体参数 ​

字段类型必填默认值描述
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

请求体参数 ​

字段类型必填默认值描述
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", // 额度扣减折扣价
      "list_price": "string" // 额度扣减刊例价
    },
    "created_at": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
  }
}

查询自定义音色(列表) ​

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

查询参数 ​

字段类型必填默认值描述
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", // 额度扣减折扣价
        "list_price": "string" // 额度扣减刊例价
      },
      "created_at": 1722769557708, // 任务创建时间,Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间,Unix时间戳、单位ms
    }
  ]
}

查询官方音色(列表) ​

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

注意:有两个官方音色不满5s,不可用

查询参数 ​

字段类型必填默认值描述
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

请求体参数 ​

字段类型必填默认值描述
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作为模型名展示计费信息