# Kling API field-level Tier 2 reference — General / Elements

Status: active working reference
Captured: 2026-03-29
Basis:
- Qingque-derived capture
- preserved extracted artifact: `samples/kling-api/pages/apiReference_model__element.txt`
- existing current docs and notes

## Purpose
Capture the Tier 2 element-management surface in field-level form from preserved source text only, while keeping clear boundaries between:
- directly observed structures
- scope/behavior notes stated in the preserved docs
- remaining unknowns that still need stronger extraction or later non-billable verification

---

# 1. General — Create Element

## Section status
- doc-derived section confirmed
- exact endpoint path preserved
- request-body rows preserved
- create response shape preserved
- invocation examples preserved:
  - Create Multi-Image Elements
  - Create Video Character Elements

## Endpoint
- method: `POST`
- path: `/v1/general/advanced-custom-elements`

## Request headers
- `Content-Type`: `string`, required, default `application/json`
- `Authorization`: `string`, required

## Request body fields
### `element_name`
- type: `string`
- required: yes
- meaning: element name
- constraint: must not exceed 20 characters

### `element_description`
- type: `string`
- required: yes
- meaning: element description
- constraint: must not exceed 100 characters

### `reference_type`
- type: `string`
- required: yes
- enum: `video_refer`, `image_refer`
- documented meaning:
  - `video_refer`: Video Character Elements; appearance defined from `element_video_list`
  - `image_refer`: Multi-Image Elements; appearance defined from `element_image_list`
- note: availability scope differs between video-customized and image-customized elements

### `element_image_list`
- type: `object`
- required: conditional
- default: `None`
- required when: `reference_type=image_refer`
- invalidity note: not the active path when referencing videos
- documented structure:
```json
"element_image_list": {
  "frontal_image": "image_url_0",
  "refer_images": [
    { "image_url": "image_url_1" }
  ]
}
```
- documented semantics:
  - at least 1 frontal reference image in `frontal_image`
  - plus 1 to 3 additional non-front reference images in `refer_images[]`
  - supports Base64 or accessible image URL
  - formats: `.jpg`, `.jpeg`, `.png`
  - size <= 10MB
  - dimensions >= 300px
  - aspect ratio between `1:2.5` and `2.5:1`

#### Recoverable child fields
##### `element_image_list.frontal_image`
- type: `string`
- status: source-grounded by preserved structure/example text
- meaning: frontal reference image
- accepted input: Base64 or accessible image URL
- constraints inherited from parent notes:
  - formats `.jpg`, `.jpeg`, `.png`
  - size <= 10MB
  - dimensions >= 300px
  - aspect ratio between `1:2.5` and `2.5:1`

##### `element_image_list.refer_images`
- type: `array`
- status: source-grounded by preserved structure/example text
- meaning: additional non-front reference images from other angles or close-ups
- documented count: `1` to `3`

##### `element_image_list.refer_images[].image_url`
- type: `string`
- status: source-grounded by preserved structure/example text
- meaning: additional reference image payload/value
- accepted input: Base64 or accessible image URL
- note: preserved source names the child key `image_url` even though Base64 is also allowed as the value form
- constraints inherited from parent notes:
  - formats `.jpg`, `.jpeg`, `.png`
  - size <= 10MB
  - dimensions >= 300px
  - aspect ratio between `1:2.5` and `2.5:1`

### `element_video_list`
- type: `object`
- required: conditional
- default: `None`
- required when: `reference_type=video_refer`
- invalid when: referencing images
- documented structure:
```json
"element_video_list": {
  "refer_videos": [
    { "video_url": "video_url_1" }
  ]
}
```
- documented semantics:
  - video defines the element details
  - audio videos may be uploaded
  - if uploaded audio video contains human voice, docs say it triggers voice customization + voice-library inclusion + binding with the element
  - currently only realistic-style humanoid figures can be customized through video
  - only `.mp4` / `.mov`
  - duration `3s–8s`
  - `1080P`
  - aspect ratio `16:9` or `9:16`
  - at most 1 video
  - size <= 200MB
  - `video_url` must not be empty
  - video-customized elements are only supported for `kling-video-o3` and later models

#### Recoverable child fields
##### `element_video_list.refer_videos`
- type: `array`
- status: source-grounded by preserved structure/example text
- meaning: reference-video container for video-customized element creation
- documented count: at most `1` video

##### `element_video_list.refer_videos[].video_url`
- type: `string`
- status: source-grounded by preserved structure/example text
- meaning: uploaded/reference video value
- constraints:
  - must not be empty
  - `.mp4` / `.mov` only
  - duration `3s–8s`
  - `1080P`
  - aspect ratio `16:9` or `9:16`
  - size <= 200MB

### `element_voice_id`
- type: `string`
- required: no
- default: `None`
- meaning: bind an existing voice/tone-library voice to the element
- note: when empty, the element is not bound to a tone color / voice
- source note: ID is obtained from voice-related API

### `tag_list`
- type: `array`
- required: no
- default: `None`
- meaning: configure one or more tags for the element
- documented structure:
```json
"tag_list": [
  { "tag_id": "o_101" },
  { "tag_id": "o_102" }
]
```
- documented tag map:
  - `o_101` = Hottest
  - `o_102` = Character
  - `o_103` = Animal
  - `o_104` = Item
  - `o_105` = Costume
  - `o_106` = Scene
  - `o_107` = Effect
  - `o_108` = Others

#### Recoverable child fields
##### `tag_list[].tag_id`
- type: `string`
- status: source-grounded by preserved structure/example text
- meaning: tag identifier for one element tag assignment
- documented enum/map:
  - `o_101` = Hottest
  - `o_102` = Character
  - `o_103` = Animal
  - `o_104` = Item
  - `o_105` = Costume
  - `o_106` = Scene
  - `o_107` = Effect
  - `o_108` = Others

### `callback_url`
- type: `string`
- required: no
- meaning: callback notification URL for task-state changes

### `external_task_id`
- type: `string`
- required: no
- meaning: custom task ID
- note: does not overwrite system task ID; must be unique within a user account

## Create response body
```json
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}
```
- `task_status` enum text in preserved source: `submitted`, `processing`, `succeed`, `failed`

---

# 2. Create Multi-Image Elements (invocation example)

## Example status
- preserved exact example body confirmed

## Example body shape
```json
{
  "element_name": "xxx",
  "element_description": "xxx",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "xxx",
    "refer_images": [
      { "image_url": "xxx" },
      { "image_url": "xxx" }
    ]
  },
  "element_voice_id": string,
  "callback_url": "xxx",
  "external_task_id": "",
  "tag_list": [
    {
      "tag_id": "xxx"
    }
  ]
}
```

## Exact strengthening from preserved source
- this example confirms the multi-image path is not just conceptual; it explicitly uses:
  - `reference_type=image_refer`
  - `element_image_list.frontal_image`
  - `element_image_list.refer_images[].image_url`
  - optional `element_voice_id`
  - optional `tag_list[].tag_id`

---

# 3. Create Video Character Elements (invocation example)

## Example status
- preserved exact example body confirmed

## Example body shape
```json
{
  "element_name": "xxx",
  "element_description": "xxx",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [
      {
        "video_url": "xxx"
      }
    ]
  },
  "element_voice_id": string,
  "callback_url": "xxx",
  "external_task_id": "",
  "tag_list": [
    {
      "tag_id": "xxx"
    }
  ]
}
```

## Exact strengthening from preserved source
- this example confirms the video-character path explicitly uses:
  - `reference_type=video_refer`
  - `element_video_list.refer_videos[].video_url`
  - optional `element_voice_id`
  - optional `tag_list[].tag_id`
- preserved docs also state audio video may trigger voice customization and binding, but that runtime behavior remains doc-derived only here

---

# 4. General — Query Custom Element (Single)

## Section status
- doc-derived section confirmed
- exact endpoint path preserved
- exact path-parameter names preserved
- exact response shape preserved

## Endpoint
- method: `GET`
- path: `/v1/general/advanced-custom-elements/{id}`
- canonical interpretation for current docs: the route family is explicit and should be treated as correct; `{id}` should be read as a generic path placeholder, while the practical selector semantics in the preserved request rows are `task_id` or `external_task_id`
- current conclusion: this is a placeholder-label inconsistency in the preserved docs, not evidence of multiple different single-query route families

## Request headers
- `Content-Type`: `string`, required, default `application/json`
- `Authorization`: `string`, required

## Path parameters
### `task_id`
- type: `string`
- required: yes in preserved table
- note: fill directly in request path

### `external_task_id`
- type: `string`
- required: no
- note: docs say choose either `external_task_id` or `task_id` for querying

## Response body shape
```json
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "string",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "elements": [
        {
          "element_id": 0,
          "element_name": "string",
          "element_description": "string",
          "reference_type": "video_refer",
          "element_image_list": {},
          "element_video_list": {},
          "element_voice_info": {
            "voice_id": "string",
            "voice_name": "string",
            "trial_url": "string",
            "owned_by": "kling"
          },
          "tag_list": [],
          "owned_by": "kling",
          "status": "succeed"
        }
      ]
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}
```

## Directly observed metadata fields
- `element_id`
- `element_name`
- `element_description`
- `reference_type`
- `element_image_list`
- `element_video_list`
- `element_voice_info.voice_id`
- `element_voice_info.voice_name`
- `element_voice_info.trial_url`
- `element_voice_info.owned_by`
- `tag_list`
- `owned_by`
- `status`

## Recoverable nested query metadata notes
### `element_voice_info.voice_id`
- type: `string`
- meaning: custom voice ID; globally unique

### `element_voice_info.voice_name`
- type: `string`
- meaning: custom voice name

### `element_voice_info.trial_url`
- type: `string`
- meaning: trial audio download URL

### `element_voice_info.owned_by`
- type: `string`
- meaning: voice source
- documented example semantics: `kling` = official; numeric value = creator ID

### `owned_by`
- type: `string`
- meaning: element source
- documented example semantics: `kling` = official element library

### `status`
- type: `string`
- meaning: element lifecycle status
- documented values visible in preserved response comments:
  - `succeed` = normal
  - `deleted` = removed

## Documented semantics
- `owned_by`: element source; `kling` means official element library
- `status`: preserved docs show `succeed` when normal, `deleted` when removed

---

# 5. General — Query Custom Element (List)

## Section status
- doc-derived section confirmed
- exact endpoint path preserved
- exact query parameters preserved
- response collection shape preserved

## Endpoint
- method: `GET`
- path: `/v1/general/advanced-custom-elements`

## Request headers
- `Content-Type`: `string`, required, default `application/json`
- `Authorization`: `string`, required

## Query parameters
### `pageNum`
- type: `int`
- required: no
- default: `1`
- range: `[1, 1000]`

### `pageSize`
- type: `int`
- required: no
- default: `30`
- range: `[1, 500]`

## Response body shape
- outer `data` is a list of task records
- each task record preserves:
  - `task_id`
  - `task_status`
  - `task_status_msg`
  - `task_info.external_task_id`
  - `task_result.elements[]`
  - `final_unit_deduction`
  - `created_at`
  - `updated_at`
- each `elements[]` item preserves the same high-level metadata cluster as the single-query route:
  - `element_id`
  - `element_name`
  - `element_description`
  - `reference_type`
  - `element_image_list`
  - `element_video_list`
  - `element_voice_info`
  - `tag_list`
  - `owned_by`
  - `status`

---

# 6. General — Query Presets Element (List)

## Section status
- doc-derived section confirmed
- exact endpoint path preserved
- exact query parameters preserved
- response shape preserved

## Endpoint
- method: `GET`
- path: `/v1/general/advanced-presets-elements`

## Request headers
- `Content-Type`: `string`, required, default `application/json`
- `Authorization`: `string`, required

## Query parameters
### `pageNum`
- type: `int`
- required: no
- default: `1`
- range: `[1, 1000]`

### `pageSize`
- type: `int`
- required: no
- default: `30`
- range: `[1, 500]`

## Response body shape
- same preserved high-level list/task envelope pattern as Query Custom Element (List)
- preserved nested `elements[]` rows include:
  - `element_id`
  - `element_name`
  - `element_description`
  - `reference_type`
  - `element_image_list`
  - `element_video_list`
  - `element_voice_info`
  - `tag_list`
  - `owned_by`
  - `status`

## Current interpretation boundary
- preserved source shows same response family as custom elements list, but practical source distinction likely depends on route + `owned_by`; this remains interpretation, not additional observed schema beyond the preserved rows

---

# 7. General — Delete Custom Element

## Section status
- doc-derived section confirmed
- exact endpoint path preserved
- exact delete-body field preserved
- response shape preserved

## Endpoint
- method: `POST`
- path: `/v1/general/delete-elements`

## Request headers
- `Content-Type`: `string`, required, default `application/json`
- `Authorization`: `string`, required

## Request body
### `element_id`
- type: `string`
- required: yes
- meaning: ID of the element to be deleted
- note: only supports deleting custom elements

## Response body
```json
{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "string"
  }
}
```
- `task_status` enum text in preserved source: `submitted`, `processing`, `succeed`, `failed`

---

# 8. Directly observed downstream attachment structure
The strongest directly observed downstream generation attachment structure remains:
```json
"element_list": [
  {
    "element_id": long
  },
  {
    "element_id": long
  }
]
```

## Current implementation meaning
- generation payloads can carry one or more reusable element IDs
- preserved Tier 2 source now makes the upstream creation/query/delete chain materially stronger, not just inferred

---

# 9. Why Tier 2 matters to the pipeline
Current inline reference methods are useful, but Tier 2 is where the more stable production workflow likely lives.

## Most likely advantages of element workflow
- reusable identity assets rather than one-off inline references
- explicit split between Multi-Image Elements and Video Character Elements
- documented voice-binding slot via `element_voice_id`
- queryable lifecycle metadata (`owned_by`, `status`, tags, bound voice info)
- explicit cleanup route via delete API

## Pipeline implication
If we want a durable production path for:
- character consistency
- product consistency
- audiovisual identity reuse
then Element APIs are likely central rather than optional.

---

# 10. What still remains blocked or weaker
Even after this extraction pass, some Tier 2 areas remain weaker than the core rows above:
1. child-field tables for `element_image_list`, `refer_images[]`, `element_video_list`, `refer_videos[]`, and `tag_list[]` are preserved by example/structure text, but not as fully separate typed child-row tables in this artifact
2. query-single path table is internally inconsistent with route placeholder `{id}` versus listed path parameters `task_id` / `external_task_id`; preserved as-is, but runtime semantics should be treated carefully until later non-billable verification
3. exact create-success response does not expose `element_id` directly; that appears later in query responses, so create -> query lifecycle should still be treated as a two-step retrieval pattern
4. no live create calls were made here, by task constraint

## Current readiness summary
- section map: strong
- exact endpoint paths: strong
- create request rows: strong
- example bodies: strong
- query/list/delete rows: strong
- remaining issues: mostly child-row granularity and path-parameter semantics, not missing top-level schema anymore