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.
Preview guide
Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.
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_KEYenvironment variable or replaceYOUR_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
| Field | Type | Required | Description / constraints |
|---|---|---|---|
| element_name | string | Yes | Element name, 1–20 characters. Example: Rabbit |
| element_description | string | Yes | Element description, 1–100 characters. Example: White cartoon rabbit with a red scarf |
| reference_type | string | Yes | image_refer (reference images) or video_refer (reference video). Example: image_refer |
| element_image_list | object | No | Required for image_refer: frontal_image plus 1–3 refer_images, as public HTTP(S) URLs or Base64. |
| element_video_list | object | No | Required for video_refer: exactly one public HTTP(S) video in refer_videos, 3–8 seconds, 1080P, MP4/MOV. |
| element_voice_id | string | No | Bind a site voice using a voice_ ID returned by /v1/general/custom-voices. Example: voice_example |
| tag_list | array | No | Tags; tag_id must be o_101–o_108. |
Response fields
| Field | Type | Description / constraints |
|---|---|---|
| data.task_id | string | Site task ID; save it for polling. |
| data.task_status | string | submitted 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.
兔子API