# Kling API field-level Tier 3 reference — image generation surfaces

Status: active working reference
Captured: 2026-03-29
Basis:
- Qingque-derived capture
- existing current docs

## Purpose
Capture the image-generation side of the Series 3 API hierarchy so the overall Qingque reference is not skewed toward video-only work.

---

# 1. Omni-Image — Create Task

## Section status
- Doc-derived section confirmed present in preserved extraction
- exact create-body rows are now transcribed from `samples/kling-api/deep-extra/apiReference_model__OmniImage.txt`
- invocation example confirmed present: Image generation with element

## Endpoint
- `POST /v1/images/omni-image`

## Exact create-body rows recovered from preserved docs
### `model_name`
- type: `string`
- status: doc-derived
- optional, default `kling-image-o1`
- enum observed:
  - `kling-image-o1`
  - `kling-v3-omni`

### `prompt`
- type: `string`
- status: doc-derived
- required
- max length: 2500 chars
- supports templated references like `<<<image_1>>>`

### `image_list[]`
- type: `array`
- status: doc-derived
- optional
- supports Base64 or URL
- supported formats: `.jpg/.jpeg/.png`
- limits:
  - max 10MB each
  - minimum dimension 300px
  - aspect ratio between `1:2.5` and `2.5:1`
- combined cap: reference elements + reference images must not exceed 10

#### Recoverable child field
##### `image_list[].image`
- type: `string`
- required: yes
- meaning: reference image payload/value for one Omni-Image input slot
- accepted input: Base64 or accessible image URL
- constraints inherited from parent notes:
  - supported formats `.jpg/.jpeg/.png`
  - max 10MB each
  - minimum dimension 300px
  - aspect ratio between `1:2.5` and `2.5:1`

### `element_list[]`
- type: `array`
- status: doc-derived
- optional
- child row observed: `element_list[].element_id` (`long`, required)
- combined cap with `image_list[]`: total references must not exceed 10

#### Recoverable child field
##### `element_list[].element_id`
- type: `long`
- required: yes
- meaning: element ID from element library

### `resolution`
- type: `string`
- status: doc-derived
- optional, default `1k`
- enum observed:
  - `1k`
  - `2k`
  - `4k`

### `result_type`
- type: `string`
- status: doc-derived
- optional, default `single`
- enum observed:
  - `single`
  - `series`

### `n`
- type: `int`
- status: doc-derived
- optional, default `1`
- range: `[1, 9]`
- invalid when `result_type=series`

### `series_amount`
- type: `int`
- status: doc-derived
- optional, default `4`
- range: `[2, 9]`
- invalid when `result_type=single`

### `aspect_ratio`
- type: `string`
- status: doc-derived
- optional, default `auto`
- enum observed:
  - `16:9`
  - `9:16`
  - `1:1`
  - `4:3`
  - `3:4`
  - `3:2`
  - `2:3`
  - `21:9`
  - `auto`
- note: docs say `auto` intelligently chooses aspect ratio from incoming content; when generating based on original-image aspect ratio, this parameter can become invalid

### `watermark_info`
- type: `object`
- status: doc-derived
- optional
- observed shape: `{ "enabled": boolean }`

#### Recoverable child field
##### `watermark_info.enabled`
- type: `boolean`
- meaning: whether to generate a watermarked result simultaneously
- documented values:
  - `true` = generate watermarked result
  - `false` = do not generate
- note: custom watermarks are not currently supported

### `callback_url`
- type: `string`
- status: doc-derived
- optional

### `external_task_id`
- type: `string`
- status: doc-derived
- optional
- must be unique per user

## Strong workflow implication
The presence of “Image generation with element” is important because it means:
- elements are not only for video generation
- the same identity/asset layer likely spans both image and video workflows
- image generation may be used to create controlled frame assets for later video generation

---

# 2. Omni-Image — Query Task (Single)

## Section status
- Doc-derived section confirmed present
- exact response-body rows transcribed from preserved text extraction

## Endpoint
- `GET /v1/images/omni-image/{id}`

## Query/result rows currently recoverable
### Path/query selectors
- `task_id` (`string`, required)
- `external_task_id` (`string`, optional)
- note: preserved text says query can be done by either `external_task_id` or `task_id`

### Response-body fields observed
- `data.task_id`
- `data.task_status`
- `data.task_status_msg`
- `data.task_info.external_task_id`
- `data.task_result.result_type`
- `data.task_result.images[].index`
- `data.task_result.images[].url`
- `data.task_result.images[].watermark_url`
- `data.task_result.series_images[].index`
- `data.task_result.series_images[].url`
- `data.task_result.series_images[].watermark_url`
- `data.watermark_info.enabled`
- `data.final_unit_deduction`
- `data.created_at`
- `data.updated_at`

### Recoverable nested response notes

#### Recoverable child fields
##### `data.task_result.images[].index`
- type: `int`-like
- meaning: image sequence number

##### `data.task_result.images[].url`
- type: `string`
- meaning: generated image URL
- note: preserved comments mention anti-hotlinking format and 30-day retention warning

##### `data.task_result.images[].watermark_url`
- type: `string`
- meaning: watermarked image download URL

##### `data.task_result.series_images[].index`
- type: `int`-like
- meaning: series-image sequence number

##### `data.task_result.series_images[].url`
- type: `string`
- meaning: generated image URL for one series result

##### `data.task_result.series_images[].watermark_url`
- type: `string`
- meaning: watermarked image download URL for one series result

##### `data.watermark_info.enabled`
- type: `boolean`
- meaning: watermark flag echoed in the result envelope

---

# 3. Omni-Image — Query Task (List)

## Section status
- Doc-derived section confirmed present
- exact list-response rows transcribed from preserved text extraction

## Endpoint
- `GET /v1/images/omni-image`

## Query/result rows currently recoverable
### Query parameters
- `pageNum` (`int`, optional, default `1`, range `[1,1000]`)
- `pageSize` (`int`, optional, default `30`)

### Response-body fields observed per item
- `task_id`
- `task_status`
- `task_status_msg`
- `task_info.external_task_id`
- `final_unit_deduction`
- `created_at`
- `updated_at`
- `watermark_info.enabled`
- `task_result.result_type`
- `task_result.images[].index`
- `task_result.images[].url`
- `task_result.images[].watermark_url`
- `task_result.series_images[].index`
- `task_result.series_images[].url`
- `task_result.series_images[].watermark_url`

---

# 4. Image Generation — Create Task

## Section status
- Doc-derived section confirmed present
- exact create-body rows are now transcribed from `samples/kling-api/deep-extra/apiReference_model__imageGeneration.txt`
- invocation example confirmed present: Image generation with element

## Endpoint
- `POST /v1/images/generations`

## Exact create-body rows recovered from preserved docs
### `model_name`
- type: `string`
- status: doc-derived
- optional, default `kling-v1`
- enum observed:
  - `kling-v1`
  - `kling-v1-5`
  - `kling-v2`
  - `kling-v2-new`
  - `kling-v2-1`
  - `kling-v3`
- note: preserved docs explicitly mention legacy `model` renamed to `model_name`

### `prompt`
- type: `string`
- status: doc-derived
- required
- max length: 2500 chars

### `negative_prompt`
- type: `string`
- status: doc-derived
- optional
- max length: 2500 chars
- not supported when `image` is present in image-to-image scenario

### `image`
- type: `string`
- status: doc-derived
- optional
- supports Base64 or URL
- Base64 must be raw encoded string without `data:image/...;base64,` prefix
- supported formats: `.jpg/.jpeg/.png`
- limits:
  - max 10MB
  - minimum dimension 300px
  - aspect ratio `1:2.5 ~ 2.5:1`

### `image_reference`
- type: `string`
- status: doc-derived
- optional
- enum observed: `subject`, `face`
- required when using `kling-v1-5` and `image` is not empty
- note: `face` requires exactly one face in uploaded image

### `image_fidelity`
- type: `float`
- status: doc-derived
- optional, default `0.5`
- range: `[0,1]`
- only `kling-v1` / `kling-v1-5`

### `human_fidelity`
- type: `float`
- status: doc-derived
- optional, default `0.45`
- range: `[0,1]`
- only available when `image_reference=subject`
- only `kling-v1-5`

### `element_list[]`
- type: `array`
- status: doc-derived
- optional
- child row observed: `element_list[].element_id` (`long`, required)
- total reference count rule: elements + reference images must not exceed 10

#### Recoverable child field
##### `element_list[].element_id`
- type: `long`
- required: yes
- meaning: element ID

### `resolution`
- type: `string`
- status: doc-derived
- optional, default `1k`
- enum observed:
  - `1k`
  - `2k`
- note: unlike Omni-Image, preserved extraction did not expose `4k` here

### `n`
- type: `int`
- status: doc-derived
- optional, default `1`
- range: `[1,9]`

### `aspect_ratio`
- type: `string`
- status: doc-derived
- optional, default `16:9`
- enum observed:
  - `16:9`
  - `9:16`
  - `1:1`
  - `4:3`
  - `3:4`
  - `3:2`
  - `2:3`
  - `21:9`

### `watermark_info`
- type: `object`
- status: doc-derived
- optional
- observed shape: `{ "enabled": boolean }`

#### Recoverable child field
##### `watermark_info.enabled`
- type: `boolean`
- meaning: whether to generate a watermarked result simultaneously
- documented values:
  - `true` = generate watermarked result
  - `false` = do not generate
- note: custom watermarks are not currently supported

### `callback_url`
- type: `string`
- status: doc-derived
- optional

### `external_task_id`
- type: `string`
- status: doc-derived
- optional
- must be unique within one user account

## Current interpretation
This likely sits alongside Omni-Image as another image-generation family or mode split in the Series 3 hierarchy. Even if our near-term pipeline is more video-centric, this matters because:
- controlled image generation may become the best source of high-quality `first_frame` / `end_frame` anchors
- element-bound image generation may help avoid degraded frame chaining workflows

---

# 5. Image Generation — Query Task (Single)

## Section status
- Doc-derived section confirmed present
- exact response-body rows transcribed from preserved text extraction

## Endpoint
- `GET /v1/images/generations/{id}`

## Query/result rows currently recoverable
### Path/query selectors
- `task_id` (`string`, required)
- `external_task_id` (`string`, optional)

### Response-body fields observed
- `data.task_id`
- `data.task_status`
- `data.task_status_msg`
- `data.final_unit_deduction`
- `data.watermark_info.enabled`
- `data.task_info.external_task_id`
- `data.created_at`
- `data.updated_at`
- `data.task_result.images[].index`
- `data.task_result.images[].url`
- `data.task_result.images[].watermark_url`

### Recoverable nested response notes
- `data.task_result.images[].index`: preserved comment says image number (`0-9` in single-query example)
- `data.task_result.images[].url`: generated image URL; preserved comments note anti-leech/anti-hotlinking style and 30-day retention warning
- `data.task_result.images[].watermark_url`: watermarked image download URL
- `data.watermark_info.enabled`: boolean watermark flag echoed in result envelope

---

# 6. Image Generation — Query Task (List)

## Section status
- Doc-derived section confirmed present
- exact list-response rows transcribed from preserved text extraction

## Endpoint
- `GET /v1/images/generations`

## Query/result rows currently recoverable
### Query parameters
- `pageNum` (`int`, optional, default `1`, range `[1,1000]`)
- `pageSize` (`int`, optional, default `30`, range `[1,500]`)

### Response-body fields observed per item
- `task_id`
- `task_status`
- `task_status_msg`
- `final_unit_deduction`
- `watermark_info.enabled`
- `task_info.external_task_id`
- `created_at`
- `updated_at`
- `task_result.images[].index`
- `task_result.images[].url`
- `task_result.images[].watermark_url`

---

# 7. Why Tier 3 matters even for a video pipeline
It is tempting to de-prioritize image-generation surfaces because the current pipeline focus is video. That would be a mistake.

## Reasons Tier 3 is strategically relevant
1. High-quality anchor generation
   - controlled images may be better first/end frames than extracted video frames
2. Element reuse
   - if elements span both image and video, Tier 3 helps build better reusable identity assets
3. Quality preservation
   - image generation can potentially produce cleaner targets than reusing degraded last frames from compressed videos
4. Scene design support
   - image generation may become a preparatory step for complex video scenes

---

# 8. Cross-tier interpretation
The full Series 3 shape increasingly looks like this:
- Tier 1: video generation / query
- Tier 2: reusable element asset management
- Tier 3: image generation / query supporting anchors and reusable visual assets

This reinforces a broader pipeline hypothesis:
- identity, continuity, and audiovisual stability are likely solved by combining image/video generation with reusable element workflows, not by prompt-only tactics alone.

---

# 9. Residual Tier 3 limits after preserved-artifact extraction
What is now closed from preserved artifacts:
1. exact Omni-Image create rows
2. exact Omni-Image query single/list response rows
3. exact Image Generation create rows
4. exact Image Generation query single/list response rows
5. image-side quality/resolution/result-shape fields now visible at field level

What remains genuinely residual:
1. capability-map-dependent support ranges remain doc-derived rather than live-validated
2. no richer nested element attachment object was found beyond `element_list[].element_id`
3. no separate image asset ID field was exposed in these preserved query responses beyond downloadable URLs
4. no live non-billable validation was performed for `4k`, `series`, or element-attached image generation in this pass

## Current readiness summary
- section map: strong
- strategic interpretation: strong
- exact field rows: strong for the preserved Omni-Image and Image Generation surfaces
- remaining blockers: mostly capability-map/runtime semantics, not missing top-level field tables