主体（新版本）

POSThttps://www.aipro2.com/kling/v1/general/advanced-custom-elements

Header 参数

• Content-Typestring
  请求体 Content-Type，一般为 application/json

  示例application/json
• Authorizationstring
  Bearer API Key

  示例Bearer {{YOUR_API_KEY}}

请求体参数

application/json

• callback_urlstring
  本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知
• element_description*string
  不能超过100个字符
• element_image_listobject
  可通过多张图片设定主体及其细节
  
  包括正面参考图和其他角度或特写参考图，其中：至少包括1张正面参考图，由frontal_image参数定义；需包括1～3张其他参考图，需与正面参考图有差异，由image_url参数定义
  
  用key:value承载，如下：
  
  "element_image_list": {
  "frontal_image": "image_url_0",
  "refer_images": [{ "image_url": "image_url_1" }, ...]
  }
  支持传入图片Base64编码或图片URL（确保可访问）
  
  图片格式支持.jpg / .jpeg / .png。图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在1:2.5 ~ 2.5:1之间
  
  reference_type参数值为 image_refer 时，当前参数必填
• element_name*string
  不能超过20个字符
• element_video_listobject
  可通过视频设定主体及其细节
  
  可上传有声视频，有声视频包含人声则触发音色定制（定制+入音色库+与主体绑定）
  
  暂时仅支持通过视频定制写实风格的人形形象
  
  参考视频时当前参数必填，参考图片时当前参数无效
  
  用key:value承载。视频格式仅支持MP4/MOV。仅支持时长介于3s～8s之间、宽高比例需为16:9或9:16的1080P视频。至多仅支持上传1段视频，视频大小不超过200MB。video_url参数值不得为空
  
  "element_video_list": {
  "refer_videos": [{ "video_url": "video_url_1" }, ...]
  }
  视频定制的主体仅支持用于 kling-video-o3 及之后的模型
• element_voice_idstring
  可绑定音色库中已有音色
  
  当前参数为空时，当前主体不绑定音色
  
  可通过音色相关API获取ID，点此查看
  
  仅视频定制的主体支持绑定音色
• external_task_idstring
  自定义任务ID。用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性
• reference_type*string
  枚举值：video_refer、 image_refer
  video_refer: 视频角色主体，此时将参考element_video_list定义主体外表
  image_refer: 多图主体，此时将参考element_image_list定义主体外表
  通过视频定制的主体和通过图片定制的主体的可用范围不同，详见能力地图和参数说明。
• tag_listarray<object>
  一个主体可以配置多个标签
  
  用key:value承载。tag的ID与名称：o_101 热梗, o_102 人物, o_103 动物, o_104 道具, o_105 服饰, o_106 场景, o_107 特效, o_108 其他

响应

application/json

无响应结构说明

请求体示例示例 1

1{
2    "element_name": "主体ysh11112311213",
3    "element_description": "测试",
4    "reference_type": "image_refer",
5    "element_image_list": {
6        "frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
7        "refer_images": [
8            {
9                "image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
10            }
11        ]
12    },
13    // "element_video_list": {
14    //     "refer_videos": [
15    //         {
16    //             "video_url": "xxx"
17    //         }
18    //     ]
19    // },
20    // "element_voice_id": string,
21    // "tag_list": [
22    //     {
23    //         "tag_id": "xxx"
24    //     }
25    // ],
26    // "callback_url": "xxx",
27    // "external_task_id": ""
28}

代码示例cURLPythonJavaScriptGoPHP

1curl -X POST "https://www.aipro2.com/kling/v1/general/advanced-custom-elements" \2  -H "Authorization: Bearer <API Key>" \3  -H "Content-Type: application/json" \4  -d '"{\r\n    \"element_name\": \"主体ysh11112311213\",\r\n    \"element_description\": \"测试\",\r\n    \"reference_type\": \"image_refer\",\r\n    \"element_image_list\": {\r\n        \"frontal_image\": \"https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png\",\r\n        \"refer_images\": [\r\n            {\r\n                \"image_url\": \"https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png\"\r\n            }\r\n        ]\r\n    },\r\n    // \"element_video_list\": {\r\n    //     \"refer_videos\": [\r\n    //         {\r\n    //             \"video_url\": \"xxx\"\r\n    //         }\r\n    //     ]\r\n    // },\r\n    // \"element_voice_id\": string,\r\n    // \"tag_list\": [\r\n    //     {\r\n    //         \"tag_id\": \"xxx\"\r\n    //     }\r\n    // ],\r\n    // \"callback_url\": \"xxx\",\r\n    // \"external_task_id\": \"\"\r\n}"'

响应示例 · 200example

1{2  "code": 0,3  "data": {4    "task_id": "task_example_001"5  },6  "message": "success"7}