主题模式
可灵主体与音色管理接口文档
本文为主体与音色管理的共用接口文档,配套以下两版生视频接口使用:
API 总览
统一请求头
| 字段 | 值 | 描述 |
|---|---|---|
| Content-Type | application/json | 数据交换格式 |
| Authorization | Bearer {api_key} | 鉴权信息 |
核心说明
统一采用
{BASE_URL}/api/v1/multimodal/kling/general/...接口路径承载可灵主体和音色能力。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 |
主体管理
重要约定
主体 ID:创建成功后返回主体唯一标识
element_id,后续查询、视频生成、删除均使用该 ID。异步状态:
status枚举为submitted(已提交、processing(处理中)、succeed(成功)、failed(失败)。创建后通常为processing或submitted,需轮询查询单个接口;后台也会自动收敛状态。可用时机:仅当
status = succeed后,该主体才可用于视频生成。
创建主体
| 网络协议 | 请求地址 | 请求方法 | 请求格式 | 响应格式 |
|---|---|---|---|---|
| https | /api/v1/multimodal/kling/general/advanced-custom-elements | POST | application/json | application/json |
请求体参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
element_name | string | 必填 | 无 | 主体名称,不能超过 20 个字符 |
element_description | string | 必填 | 无 | 主体描述,不能超过 100 个字符 |
reference_type | string | 必填 | 无 | 主体参考方式,枚举:image_refer(多图主体)、video_refer(视频角色主体) |
element_image_list | object | 条件必填 | 无 | reference_type=image_refer 时必填。含 1 张正面参考图与 1~3 张其他参考图 |
element_video_list | object | 条件必填 | 无 | reference_type=video_refer 时必填。至多 1 段视频;含人声时触发音色定制 |
element_voice_id | string | 可选 | 无 | 绑定音色库中已有音色 ID |
tag_list | array | 可选 | 无 | 主体标签列表,如 [{"tag_id":"o_102"}] |
external_task_id | string | 可选 | 无 | 自定义任务 ID(单用户内需唯一) |
callback_url | string | 可选 | 无 | 任务结果回调地址(透传可灵) |
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} | GET | application/json | application/json |
路径参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
task_id | string | 必填 | 无 | 主体 ID(创建时返回的 task_id)。 |
external_task_id | string | 可选 | 无 | 自定义任务 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-elements | GET | application/json | application/json |
查询参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
pageNum | int | 可选 | 1 | 页码,取值范围 [1, 1000] |
pageSize | int | 可选 | 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-elements | GET | application/json | application/json |
查询参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
pageNum | int | 可选 | 1 | 页码,取值范围 [1, 1000] |
pageSize | int | 可选 | 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-elements | POST | application/json | application/json |
请求体参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
element_id | string | 必填 | 无 | 要删除的主体 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-voices | POST | application/json | application/json |
请求体参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| voice_name | string | 是 | 无 | 音色名称:文本内容最大长度20个字符,创建后不再使用的音色可以通过API删除 |
| voice_url | string | 否 | 无 | 音色数据文件获取URL。 支持 .mp3 / .wav / .mp4 / .mov 格式的音视频文件,音频中人声需干净无杂音,有且只能有一种人声,时长不短于 5 秒且不长于 30 秒 |
| video_id | string | 否 | 无 | 历史作品 ID,可通过引用历史作品提供音频素材。仅满足以下条件的视频可以用于定制音色:1.使用 V2.6 版本模型生成且开启 sound 参数值为 on 的视频 2.通过数字人 API 生成的视频 3.通过对口型 API 生成的视频。音频中人声需干净无杂音,有且只能有一种人声,时长不短于 5 秒且不长于 30 秒。 |
| external_task_id | string | 否 | 无 | 自定义任务 ID。传入不会覆盖系统生成的任务 ID,但支持通过该 ID 进行任务查询,请注意,单用户下需要保证唯一性。 |
| callback_url | string | 否 | 无 | 本次任务结果回调通知地址,如果配置,服务端会在任务状态发生变更时主动通知。 |
请求示例
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} | GET | application/json | application/json |
请求体参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| task_id | string | 是 | 无 | 创建音色返回的任务 ID |
| external_task_id | string | 否 | 无 | 使用自定义任务 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-voices | GET | application/json | application/json |
查询参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| pageNum | int | 否 | 1 | 页码,取值范围 [1, 1000] |
| pageSize | int | 否 | 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-voices | GET | application/json | application/json |
注意:有两个官方音色不满5s,不可用
查询参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| pageNum | int | 否 | 1 | 页码,取值范围 [1, 1000] |
| pageSize | int | 否 | 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-voices | POST | application/json | application/json |
请求体参数
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| voice_id | string | 必填 | 无 | 要删除的音色 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作为模型名展示计费信息