可灵 AI 主体管理 API 文档（新版 / advanced）

新版主体（Element）基于可灵高级版接口，支持图片或视频参考创建主体，并可绑定/定制音色。 与旧版（/v1/elements/*，同步返回）不同，新版为异步任务制：创建后先返回主体 ID，需轮询查询单个接口直到状态为 succeed。本文档以项目实现为主。

官方文档入口（仅参考）：

• https://klingai.com/document-api/

重要约定

1. 主体 ID：创建成功后返回主体唯一标识 element_id（形如 elem_lp_xxxxx），后续查询、视频生成、删除均使用该 ID。
2. 异步状态：status 枚举为 pending（处理中）、succeed（成功）、failed（失败）。创建后通常为 pending，需轮询查询单个接口；后台也会自动收敛状态。
3. 可用时机：仅当 status = succeed 后，该主体才可用于视频生成。

创建主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	/v1/kling/general/advanced-custom-elements	POST	application/json	application/json

请求头

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

请求体参数

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

"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 结构

"element_video_list": {
  "refer_videos": [{ "video_url": "video_url_1" }]
}

• 视频格式 MP4/MOV，时长 3s~8s，宽高比 16:9 或 9:16 的 1080P，至多 1 段，大小 ≤ 200MB。
• 视频定制的主体仅支持用于 kling-video-o3 及之后的模型。

请求示例（图片定制）

curl -sS -X POST \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/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" }]
  }'

请求示例（视频定制）

{
  "element_name": "视频主体",
  "element_description": "通过视频定制的主体",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [{ "video_url": "https://example.com/video.mp4" }]
  },
  "element_voice_id": ""
}

创建返回

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "element_name": "测试主体",
    "status": "pending",
    "reference_type": "image_refer"
  }
}

element_id 为后续查询/使用的统一主体 ID；status=pending 表示仍在处理，需轮询查询单个接口。

查询自定义主体（单个）

网络协议	请求地址	请求方法	请求格式	响应格式
https	/v1/kling/general/advanced-custom-elements/{task_id}	GET	application/json	application/json

请求头

字段	值	描述
Authorization	Bearer	鉴权信息

路径参数

字段	类型	必填	默认值	描述
task_id	string	必填	无	主体 ID（创建时返回的 task_id）。

请求示例

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

查询返回

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "element_name": "测试主体",
    "status": "succeed",
    "reference_type": "image_refer"
  }
}

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

查询自定义主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	/v1/kling/general/advanced-custom-elements	GET	application/json	application/json

查询参数

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

查询返回

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
      "element_name": "测试主体",
      "status": "succeed",
      "reference_type": "image_refer"
    }
  ]
}

查询官方主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	/v1/kling/general/advanced-presets-elements	GET	application/json	application/json

查询参数

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

删除主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	/v1/kling/general/delete-elements	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

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

请求示例

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

删除返回

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "status": "deleted"
  }
}