{
  "Parameters": "\"task_info\": { //Task creation parameters\n\"external_task_id\": \"string\" //Customer-defined task ID\n},\n\"task_status\": \"string\", //Task status: submitted, processing, succeed, failed\n\"created_at\": 1722769557708, //Task creation time, Unix timestamp, ms\n\"updated_at\": 1722769557708 //Task update time, Unix timestamp, ms\n}\n}\n💡\nThe service related to creating entities has been upgraded to a brand new version. If you need to browse the old version, please proceed to:Kling AI (OLD VERSION) ELEMENTS API Specification\nRequest Header\nContent-Type\nstring\nRequired\nDefault to application/json\nData Exchange Format\nAuthorization\nstring\nRequired\nAuthentication information, refer to API authentication\nRequest Body\nelement_name\nstring\nRequired\nElement Name\nMust not exceed 20 characters.\nelement_description\nstring\nRequired\nElement Description\nMust not exceed 100 characters.\nreference_type\nstring\nRequired\nReference Method\nEnum values：\nvideo_refer\nimage_refer\nvideo_refer: Video Character Elements, at this time, the subject's appearance will be defined with reference to element_video_list.\nimage_refer: Multi-Image Elements, whose appearance will be defined with reference to the element_image_list.\nThe scope of availability differs between entities customized through videos and those customized through images. Please refer to the capability map and parameter specifications for details.\nelement_image_list\nobject\nOptional\nDefault to None\nThe main reference image allows for the setting of the element and its details through multiple images.\nInclude front reference images and reference images from other angles or close-ups: at least one frontal reference image (frontal_image), and 1 to 3 additional reference images (image_url) that differ from the front.\nLoad with key:value format as follows:\n\"element_image_list\": {\n\"frontal_image\": \"image_url_0\",\n\"refer_images\": [{ \"image_url\": \"image_url_1\" }, ...]\n}\nSupports inputting image Base64 encoding or image URL (ensure accessibility).\nSupported image formats: .jpg / .jpeg / .png. Image file size cannot exceed 10MB, dimensions not less than 300px, aspect ratio between 1:2.5 ~ 2.5:1.\nWhen reference_type is image_refer, this parameter is required.\nelement_video_list\nobject\nOptional\nDefault to None\nThe element is referenced by the video, and its details can be set through the video.\nAudio videos can be uploaded. If the audio video contains human voice, it will trigger voice customization (customization + inclusion in voice library + binding with the element).\nCurrently, only realistic-style humanoid figures can be customized through video.\nRequired when referencing videos; invalid when referencing images.\nStructure: element_video_list: { refer_videos: [{ video_url: \"video_url_1\" }] }. Only .mp4/.mov formats. Duration 3s–8s, 1080P, aspect ratio 16:9 or 9:16. At most 1 video, size not exceeding 200MB. video_url must not be empty.\n\"element_video_list\": {\n\"refer_videos\": [{ \"video_url\": \"video_url_1\" }, ...]\n}\nVideo-customized elements are only supported for kling-video-o3 and later models.\nelement_voice_id\nstring\nOptional\nDefault to None\nThe voice ID of element can be bound to existing tone colors in the tone library\nWhen the current parameter is empty, the current entity is not bound to a tone color.\nThe ID can be obtained through the voice-related API. For details, see Voice Guide\ntag_list\narray\nOptional\nDefault to None\nConfigure tags for the subject, one subject can configure multiple tags.\nStructure: tag_list: [{ tag_id: \"o_101\" }, { tag_id: \"o_102\" }, ...]. Tag ID and name: o_101 Hottest, o_102 Character, o_103 Animal, o_104 Item, o_105 Costume, o_106 Scene, o_107 Effect, o_108 Others.\n\"tag_list\": [ { \"tag_id\": \"o_101\" }, { \"tag_id\": \"o_102\" } ]\nTag and tag_id correspondence:\ntag_id\ttag_name\no_101\tHottest\no_102\tCharacter\no_103\tAnimal\no_104\tItem\no_105\tCostume\no_106\tScene",
  "Callback Protocol": "For the specific message schema, see Callback Protocol\nexternal_task_id\nstring\nOptional\nCustomized Task ID. Users can provide a customized task ID, which will not overwrite the system-generated task ID but can be used for task queries. Please note that the customized task ID must be unique within a single user account.\nInvocation examples\nCreate Multi-Image Elements\ncurl --location 'https://xxx/v1/general/advanced-custom-elements/' \\\n--header 'Authorization: Bearer xxx' \\\n--header 'Content-Type: application/json\\' \\\n--data '{\n\"element_name\": \"xxx\",\n\"element_description\": \"xxx\",\n\"reference_type\": \"image_refer\",\n\"element_image_list\": {\n\"frontal_image\": \"xxx\",\n\"refer_images\": [\n{\"image_url\": \"xxx\"},\n{\"image_url\": \"xxx\"}\n]\n},\n\"element_voice_id\": string,\n\"callback_url\": \"xxx\",\n\"external_task_id\": \"\",\n\"tag_list\": [\n{\n\"tag_id\": \"xxx\"\n}\n]\n}'\nCreate Video Character Elements\ncurl --location 'https://xxx/v1/general/advanced-custom-elements/' \\\n--header 'Authorization: Bearer xxx' \\\n--header 'Content-Type: application/json\\' \\\n--data '{\n\"element_name\": \"xxx\",\n\"element_description\": \"xxx\",\n\"reference_type\": \"video_refer\",\n\"element_video_list\": {\n\"refer_videos\": [\n{\n\"video_url\": \"xxx\"\n}\n]\n},\n\"element_voice_id\": string,\n\"callback_url\": \"xxx\",\n\"external_task_id\": \"\",\n\"tag_list\": [\n{\n\"tag_id\": \"xxx\"\n}\n]\n}'\nQuery Custom Element (Single)\nGET\n/v1/general/advanced-custom-elements/{id}\n200\nCopy\nCollapse\n{\n\"code\": 0, //Error codes; specific definitions see Error codes\n\"message\": \"string\", //Error information\n\"request_id\": \"string\", //Request ID, generated by the system\n\"data\": {\n\"task_id\": \"string\", //Task ID, generated by the system\n\"task_status\": \"string\", //Task status: submitted, processing, succeed, failed\n\"task_status_msg\": \"string\", //Task status message, failure reason when failed\n\"task_info\": { //Task creation parameters\n\"external_task_id\": \"string\" //Customer-defined task ID\n},\n\"task_result\": {\n\"elements\": [\n{\n\"element_id\": 0,\n\"element_name\": \"string\",\n\"element_description\": \"string\",\n\"reference_type\": \"video_refer\",\n\"element_image_list\": {},\n\"element_video_list\": {},\n\"element_voice_info\": {\n\"voice_id\": \"string\", //Custom voice ID; globally unique\n\"voice_name\": \"string\", //Custom voice name\n\"trial_url\": \"string\", //Trial audio download URL\n\"owned_by\": \"kling\" //Voice source, kling is official, number is creator ID\n},\n\"tag_list\": [],\n\"owned_by\": \"kling\", //Element source, kling is official element library\n\"status\": \"succeed\" //Element status: succeed when normal, deleted when removed\n}"
}