4Z API

Main body (new version)

Endpoint: POST https://4zapi.com/kling/v1/general/advanced-custom-elements

Parameters

  • Content-Type (header, string): Request body Content-Type, usually application/json
  • Authorization (header, string): Bearer API Key

Request body (application/json)

  • element_description (string, required): max 100 characters
  • element_name (string, required): max 20 characters
  • reference_type (string, required): enum: video_refer、 image_refer video_refer: video subject; appearance from element_video_list image_refer: multi-image subject; appearance from element_image_list Video- vs image-customized subjects differ in availability; see capability map / params.
  • callback_url (string): Task result callback URL; if set, server notifies on status changes
  • element_image_list (object): Define subject via multiple images: at least one frontal_image plus 1–3 differing refer_images (image_url). As key:value element_image_list. Base64 or URL; .jpg/.jpeg/.png; max 10MB; min 300px; aspect 1:2.5–2.5:1. Required when reference_type=image_refer
  • element_video_list (object): Define subject via video. Video with speech triggers voice customization. Realistic humans only for now. Required for video reference; ignored for image reference. MP4/MOV; 3–8s; 16:9 or 9:16 1080P; one clip ≤200MB; video_url required. Video-customized subjects only on kling-video-o3+
  • element_voice_id (string): can bind an existing voice from the library when this parameter is empty, this subject is not bound to a voice get IDs via voice APIs only video-customized subjects support voice binding
  • external_task_id (string): Custom task ID. Does not override the system task ID, but can be used for queries. Must be unique per user
  • tag_list (array<object>): A subject can have multiple tags as key:value. Tag IDs/names: o_101 meme, o_102 person, o_103 animal, o_104 prop, o_105 clothing, o_106 scene, o_107 VFX, o_108 other

Request example

{
  "element_description": "测试",
  "element_image_list": {
    "frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
    "refer_images": [
      {
        "image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
      }
    ]
  },
  "element_name": "主体ysh11112311213",
  "reference_type": "image_refer"
}