API Reference

Create a Kling element

Create a site element for kling-4.0 from reference images or a video to keep a character or object consistent across videos.

POST https://api.tu-zi.com/v1/general/advanced-custom-elements
Preview guide

Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.

Preview guide

Create a Kling element

Updated · Reviewed

Endpoint and authentication

POST https://api.tu-zi.com/v1/general/advanced-custom-elements

Transport: json

Use an inference API key. Examples contain placeholders; read credentials from environment variables.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Before calling

  • Examples use this site's address. For another gateway, replace only the site address and keep the full endpoint path.
  • Use an inference key created on this site's token page. Set the API_KEY environment variable or replace YOUR_API_KEY, as shown in the selected example.

Constraints

application/json only; no model field is needed. A model-restricted key must allow kling-custom-element, and kling-4.0 for video generation. Request bodies are limited to 16 MiB. callback_url, external_task_id, listing and deletion are not supported. A bound voice must be completed and created with the same API key.

Minimal request example

{
  "element_name": "Rabbit",
  "element_description": "White cartoon rabbit with a red scarf",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://example.com/front.png",
    "refer_images": [
      {
        "image_url": "https://example.com/side.png"
      }
    ]
  }
}

Confirming success

Check HTTP status, the business status in the body and the required result fields. Do not rely only on HTTP 200 or the script exit code.

Follow the asynchronous workflow to a successful terminal state and verify readable output. A task ID, queued or processing is not completed generation.

Body parameters

FieldTypeRequiredDescription / constraints
element_namestringYesElement name, 1–20 characters. Example: Rabbit
element_descriptionstringYesElement description, 1–100 characters. Example: White cartoon rabbit with a red scarf
reference_typestringYesimage_refer (reference images) or video_refer (reference video). Example: image_refer
element_image_listobjectNoRequired for image_refer: frontal_image plus 1–3 refer_images, as public HTTP(S) URLs or Base64.
element_video_listobjectNoRequired for video_refer: exactly one public HTTP(S) video in refer_videos, 3–8 seconds, 1080P, MP4/MOV.
element_voice_idstringNoBind a site voice using a voice_ ID returned by /v1/general/custom-voices. Example: voice_example
tag_listarrayNoTags; tag_id must be o_101–o_108.

Response fields

FieldTypeDescription / constraints
data.task_idstringSite task ID; save it for polling.
data.task_statusstringsubmitted only means accepted.

Illustrative response; some endpoints show essential fields only. Optional fields may be absent.

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_example",
    "task_status": "submitted"
  }
}

Asynchronous workflow

Poll GET /v1/general/advanced-custom-elements/{task_id} with the same site API key. Wait on submitted/processing, read data.task_result.elements[0].element_id on succeed, and stop on failed. Polling has no model generation charge; creation and video generation are charged separately. Save task_id and bound polling by a deadline. Check task logs after a lost creation response; do not automatically repeat POST.

Errors and retries

Check HTTP status and protocol-specific errors; do not mix error formats across protocols.

  • 401/403: check credentials and permissions.
  • 429: classify temporary throttling, exhausted quota, or service capacity failure; only transient failures merit bounded backoff.
  • 5xx: inspect the gateway, upstream, and model/channel configuration.

Error bodies may contain error/message/code depending on the protocol.

  • Use bounded exponential backoff for reads encountering transient errors; fix parameter, authentication, quota, or configuration failures first.
  • Do not blindly retry task creation, generation, or key mutations, to avoid duplicate billing or execution.