# Kling API field-level Tier 1 reference

Status: active working reference
Captured: 2026-03-29
Basis:
- Qingque-derived capture under `samples/kling-api/qingque-deep/`
- existing current docs
- live findings recorded during current pipeline work

## Purpose
This document expands Tier 1 pipeline-critical surfaces into more explicit field-level reference blocks.

---

# 1. Omni-Video — Create Task

## Section status
- Doc-derived section confirmed present in Qingque capture
- Live endpoint confirmed working: `POST /v1/videos/omni-video`

## Known request-body fields (doc-derived + live)

### `model_name`
- type: string
- status: live-confirmed (exists and works)
- known live value: `kling-v3-omni`
- other doc-derived values may exist elsewhere, but current pipeline policy only allows 3.0 / 3.0 Omni models

### `prompt`
- type: string
- status: doc-derived + live-confirmed
- notes: used for text-driven scene description and also alongside references

### `duration`
- type: string in observed examples
- status: doc-derived + live-confirmed
- live-confirmed values in current work: `5`, `15`
- continuity relevance: 15s is now treated as the single-scene ceiling in our pipeline

### `mode`
- type: string
- status: doc-derived + live-confirmed
- live-confirmed value: `std`
- doc/live note: `standard` rejected live; `std` valid
- doc hint: Professional Mode / 1080P / higher quality output appears elsewhere in Qingque text

### `aspect_ratio`
- type: string
- status: doc-derived + live-confirmed
- live-confirmed example: `16:9`

### `multi_shot`
- type: boolean
- status: doc-derived + live-confirmed
- conditional rule from doc/live: when `multi_shot=false`, `shot_type` and `multi_prompt` are invalid

### `shot_type`
- type: string
- status: doc-derived + live-confirmed
- known doc/live value: `customize`
- doc-derived conditional note: when `shot_type=customize`, corresponding shot config must not be empty

### `multi_prompt[]`
- type: array
- status: doc-derived + live-confirmed
- doc-derived structure:
```json
"multi_prompt": [
  {
    "index": int,
    "prompt": "string",
    "duration": "5"
  }
]
```
- live-confirmed rules:
  - each entry needs `index`
  - each entry needs `duration`
  - `prompt` present in SOT structure

### `image_list[]`
- type: array
- status: doc-derived + live-confirmed
- doc-derived structure:
```json
"image_list": [
  {
    "image_url": "image_url",
    "type": "first_frame"
  },
  {
    "image_url": "image_url",
    "type": "end_frame"
  }
]
```
- doc-derived notes:
  - described as Reference Image List
  - `image_url` supports Base64 or URL
- live-confirmed:
  - `image_list[].image_url + type='first_frame'` works
- live-rejected:
  - `image_list[].image`
  - `image_list[].image + index`

### `video_list[]`
- type: array
- status: doc-derived, partially live-confirmed
- doc-derived structure:
```json
"video_list": [
  {
    "video_url": "video_url",
    "refer_type": "base",
    "keep_original_sound": "yes"
  }
]
```
- doc-derived note:
  - only `.mp4` / `.mov` supported
- live findings:
  - `video_url=<base64 video>` rejected with “Video URL is invalid”
  - `video_url=<remote url>` create/query succeeded and downloaded output successfully
- interpretation:
  - `video_url` likely expects an actual reachable URL, not inline base64 video

### `element_list[]`
- type: array
- status: doc-derived
- doc-derived structure:
```json
"element_list": [
  {
    "element_id": long
  }
]
```
- live status: not yet verified in intended generation flow
- interpretation: likely binds pre-created reusable assets

## Known invalid / caution cases
- `image_list[].image` should be treated as rejected for Omni
- `video_url` as a top-level improvised field should be treated as invalid methodology
- create success does not prove reference semantics; result quality/adherence must still be judged

## Current pipeline interpretation
For one-scene Omni generation, current strongest image-reference path is:
- `image_list[].image_url + type='first_frame'`

For video-driven continuation, current strongest doc/live-aligned path is:
- `video_list[].video_url=<remote url>`

---

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

## Section status
- Doc-derived section confirmed present
- Live confirmed working

## Known structure
- Request Header
- Request Path Parameters
- Request Body
- Response Body

## Important live response fields observed
### `task_id`
- status: live-confirmed

### `task_status`
- status: live-confirmed
- observed values: `submitted`, `processing`, `succeed`, `failed`

### `task_status_msg`
- status: live-confirmed
- used for failure explanation when present

### `task_result`
- status: live-confirmed
- observed nested payloads include:
  - `videos[]`
  - sometimes images depending on task family

### `final_unit_deduction`
- status: live-confirmed
- used as the most reliable per-task cost signal in current work

---

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

## Section status
- Doc-derived section confirmed present
- list-query existence confirmed in live understanding, but current work has focused more heavily on single-query

## Known structure from capture
- Request Header
- Query Parameters
- Request Body
- Response Body

---

# 4. Text to Video — Create Task

## Section status
- doc-derived section confirmed present
- exact create-body field rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__textToVideo.txt`
- live endpoint path confirmed working for text2video family

## Exact create-body rows recovered from preserved docs
### `model_name`
- status: doc-derived + live-confirmed family path exists
- type: `string`
- required: Optional
- default: `kling-v1`
- enum values:
  - `kling-v1`
  - `kling-v1-6`
  - `kling-v2-master`
  - `kling-v2-1-master`
  - `kling-v2-5-turbo`
  - `kling-v2-6`
  - `kling-v3`
- note: live compatibility should still be treated separately from doc allowlists

### `multi_shot`
- status: doc-derived
- type: `boolean`
- required: Optional
- default: `false`
- rules:
  - when `true`, `prompt` is invalid
  - first/end frame generation is not supported
  - when `false`, `shot_type` and `multi_prompt` are invalid

### `shot_type`
- status: doc-derived
- type: `string`
- required: Optional
- enum values:
  - `customize`
  - `intelligence`
- rule: required when `multi_shot=true`

### `prompt`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- meaning: positive text prompt
- rules:
  - cannot exceed 2500 characters
  - supports templating with `<<<element_1>>>`, `<<<image_1>>>`, `<<<video_1>>>`
  - supports `<<<voice_1>>>` speaker binding
  - up to 2 voices when using `voice_list`
  - when specifying voice, `sound` must be `on`
  - when `voice_list` is not empty and prompt references voice ID, task is billed as voice generation
  - when `multi_shot=false` or `shot_type=intelligence`, this field must not be empty

### `multi_prompt`
- status: doc-derived
- type: `array`
- required: Optional
- rules:
  - each storyboard cue may include positive and negative descriptions
  - supports up to 6 storyboards, minimum 1
  - each storyboard prompt max length 512 characters
  - each storyboard duration must be >=1 and must not exceed total task duration
  - sum of storyboard durations must equal total task duration
  - example shape: `{"index":int,"prompt":"string","duration":"5"}`
  - required when `multi_shot=true` and `shot_type=customize`

### `negative_prompt`
- status: doc-derived
- type: `string`
- required: Optional
- rules:
  - cannot exceed 2500 characters
  - docs recommend supplementing via negative sentences within positive prompts

### `sound`
- status: doc-derived
- type: `string`
- required: Optional
- default: `off`
- enum values: `on`, `off`

### `cfg_scale`
- status: doc-derived
- type: `float`
- required: Optional
- default: `0.5`
- range: `[0, 1]`
- note: `kling-v2.x` models do not support this parameter

### `mode`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- default: `std`
- enum values: `std`, `pro`
- meanings:
  - `std` = standard/basic/cost-effective
  - `pro` = expert/high-quality
- live note: `std` valid, `standard` invalid

### `camera_control`
- status: doc-derived
- type: `object`
- required: Optional
- note: camera movement control object
- child `type` enum values:
  - `simple`
  - `down_back`
  - `forward_up`
  - `right_turn_forward`
  - `left_turn_forward`
- child `config` rule:
  - required when `type=simple`
  - choose exactly one non-zero field among `horizontal`, `vertical`, `pan`, `tilt`, `roll`, `zoom`
  - each range: `[-10, 10]`

### `aspect_ratio`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- default: `16:9`
- enum values:
  - `16:9`
  - `9:16`
  - `1:1`

### `duration`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- default: `5`
- enum values: `3` through `15`
- live note: current minimum successful path previously recorded at `5`

### `watermark_info`
- status: doc-derived
- type: `object`
- required: Optional
- note: shaped as `{ "enabled": boolean }`

### `callback_url`
- status: doc-derived
- type: `string`
- required: Optional
- note: callback target for task-status updates

### `external_task_id`
- status: doc-derived + live-confirmed family usage
- type: `string`
- required: Optional
- rules:
  - custom task ID
  - does not overwrite system task ID
  - can be used for task queries
  - must be unique within one user account

### Multi-shot invocation example
- preserved docs include explicit `Text To Video with Multiple Shot` example
- example confirms:
  - `model_name="kling-v3"`
  - `multi_shot=true`
  - `shot_type="customize"`
  - six `multi_prompt` entries with explicit `index/prompt/duration`
  - `duration="15"`
  - `mode="pro"`
  - `sound="on"`
  - `aspect_ratio="9:16"`

---

# 5. Text to Video — Query Task (Single)

## Section status
- exact path/query selector and response-body rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__textToVideo.txt`
- status: doc-derived
- live family query existence was already known; this pass closes the preserved row-level gap

## Exact query rows recovered from preserved docs
### Endpoint / path form
- rendered section title path: `GET /v1/videos/text2video/{id}`
- cURL example path: `GET /v1/videos/text2video/{task_id}`
- canonical interpretation for current docs: the path family is explicit and should be treated as correct; `{id}` should be read as a generic path placeholder, while the practical selector semantics are `task_id` or `external_task_id` as described in the preserved request rows
- current conclusion: this is a placeholder-label inconsistency in the preserved docs, not evidence of multiple different query route families

### Path/query selectors
#### `task_id`
- status: doc-derived
- type: `string`
- required: Optional
- note: fill directly in request path
- note: choose either `task_id` or `external_task_id` for querying

#### `external_task_id`
- status: doc-derived
- type: `string`
- required: Optional
- note: customized task ID for text-to-video
- note: fill directly in request path
- note: choose either `task_id` or `external_task_id` for querying

## Response body rows recovered from preserved docs
### Top-level envelope
- `code`
- `message`
- `request_id`
- `data`

### `data.task_id`
- status: doc-derived
- type: `string`
- meaning: task ID generated by the system

### `data.task_status`
- status: doc-derived
- type: `string`
- enum values: `submitted`, `processing`, `succeed`, `failed`

### `data.task_status_msg`
- status: doc-derived
- type: `string`
- meaning: failure/status information when task fails
- preserved note mentions platform content-risk-control as an example failure reason

### `data.task_info.external_task_id`
- status: doc-derived
- type: `string`
- meaning: customer-defined task ID

### `data.task_result.videos[]`
- status: doc-derived
- child rows recovered:
  - `id` — generated video ID; globally unique
  - `url` — generated video URL; preserved note says generated images/videos are cleared after 30 days, so save promptly
  - `watermark_url` — watermarked video download URL, anti-leech format
  - `duration` — total video duration, unit `s`

### `data.watermark_info.enabled`
- status: doc-derived
- type: `boolean`

### `data.final_unit_deduction`
- status: doc-derived
- type: `string`
- meaning: deduction units of task

### `data.created_at`
- status: doc-derived
- type: timestamp-like integer example
- meaning: Unix timestamp in `ms`

### `data.updated_at`
- status: doc-derived
- type: timestamp-like integer example
- meaning: Unix timestamp in `ms`

# 6. Text to Video — Query Task (List)

## Section status
- exact query parameters and response-body rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__textToVideo.txt`
- status: doc-derived

## Endpoint / query form
- path: `GET /v1/videos/text2video`
- preserved example: `GET /v1/videos/text2video?pageNum=1&pageSize=30`

## Query parameters
### `pageNum`
- status: doc-derived
- type: `int`
- required: Optional
- default: `1`
- meaning: page number
- range: `[1, 1000]`

### `pageSize`
- status: doc-derived
- type: `int`
- required: Optional
- default: `30`
- meaning: number of items per page
- range: `[1, 500]`

## Response body rows recovered from preserved docs
### Top-level envelope
- `code`
- `message`
- `request_id`
- `data[]`

### Per-item rows in `data[]`
- `task_id`
- `task_status` (`submitted|processing|succeed|failed`)
- `task_status_msg`
- `task_info.external_task_id`
- `task_result.videos[]`
  - `id`
  - `url`
  - `watermark_url`
  - `duration`
- `watermark_info.enabled`
- `final_unit_deduction`
- `created_at`
- `updated_at`

---

# 7. Image to Video — Create Task

## Section status
- doc-derived section confirmed present
- exact create-body field rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__imageToVideo.txt`
- live family path confirmed working

## Exact create-body rows recovered from preserved docs
### `model_name`
- status: doc-derived + live-confirmed family path exists
- type: `string`
- required: Optional
- default: `kling-v1`
- enum values:
  - `kling-v1`
  - `kling-v1-5`
  - `kling-v1-6`
  - `kling-v2-master`
  - `kling-v2-1`
  - `kling-v2-1-master`
  - `kling-v2-5-turbo`
  - `kling-v2-6`
  - `kling-v3`

### `image`
- status: doc-derived + live-confirmed family usage
- type: `string`
- required: Optional
- meaning: reference image
- rules:
  - supports raw base64 or image URL
  - when using base64, do not include any `data:image/...;base64,` prefix
  - supported formats: `.jpg`, `.jpeg`, `.png`
  - file size <= 10MB
  - dimensions min 300px
  - aspect ratio `1:2.5 ~ 2.5:1`
  - at least one of `image` or `image_tail` must be provided

### `image_tail`
- status: doc-derived
- type: `string`
- required: Optional
- meaning: end-frame control image
- rules:
  - supports raw base64 or image URL
  - supported formats: `.jpg`, `.jpeg`, `.png`
  - file size <= 10MB
  - dimensions min 300px
  - at least one of `image` or `image_tail` must be provided
  - `image_tail`, `dynamic_masks`/`static_mask`, and `camera_control` are mutually exclusive

### `multi_shot`
- status: doc-derived
- type: `boolean`
- required: Optional
- default: `false`
- rules:
  - when `true`, `prompt` is invalid and first/end frame generation is not supported
  - when `false`, `shot_type` and `multi_prompt` are invalid

### `shot_type`
- status: doc-derived
- type: `string`
- required: Optional
- enum values:
  - `customize`
  - `intelligence`
- rule: required when `multi_shot=true`

### `prompt`
- status: doc-derived + live-confirmed family usage
- type: `string`
- required: Optional
- rules:
  - cannot exceed 2500 characters
  - when `multi_shot=false` or `shot_type=intelligence`, this field must not be empty
  - supports `<<<element_1>>>`, `<<<image_1>>>`, `<<<video_1>>>`
  - supports `<<<voice_1>>>` speaker binding
  - up to 2 referenced voices
  - when specifying voice, `sound` must be `on`
  - when `voice_list` is not empty and prompt references voice ID, task is billed as specified voice

### `multi_prompt`
- status: doc-derived
- type: `array`
- required: Optional
- rules:
  - supports up to 6 storyboards, minimum 1
  - each storyboard prompt max length 512 characters
  - each storyboard duration must be >=1 and must not exceed total task duration
  - sum of storyboard durations must equal total task duration
  - example shape: `{"index":int,"prompt":"string","duration":"5"}`
  - required when `multi_shot=true` and `shot_type=customize`

### `negative_prompt`
- status: doc-derived
- type: `string`
- required: Optional
- rules:
  - cannot exceed 2500 characters
  - docs recommend supplementing via negative sentences within positive prompts

### `element_list`
- status: doc-derived
- type: `array`
- required: Optional
- rules:
  - supports up to 3 reference elements
  - shape: `{ "element_id": long }`
  - elements are split between video customization elements and image customization elements
- child field:
  - `element_id` (`long`, required)

### `voice_list`
- status: doc-derived
- type: `array`
- required: Optional
- rules:
  - up to 2 voices
  - uses `voice_id` from voice customization / preset voices, not Lip-Sync API voice IDs
  - `element_list` and `voice_list` are mutually exclusive
  - shape: `{ "voice_id": "voice_id_1" }`

### `sound`
- status: doc-derived + live-confirmed family usage
- type: `string`
- required: Optional
- default: `off`
- enum values: `on`, `off`

### `cfg_scale`
- status: doc-derived
- type: `float`
- required: Optional
- default: `0.5`
- range: `[0, 1]`
- note: `kling-v2.x` models do not support this parameter

### `mode`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- default: `std`
- enum values: `std`, `pro`
- live note: `std` valid, `standard` invalid

### `static_mask`
- status: doc-derived
- type: `string`
- required: Optional
- rules:
  - supports raw base64 or image URL
  - supported formats: `.jpg`, `.jpeg`, `.png`
  - aspect ratio must match `image`
  - resolution must match `dynamic_masks.mask` if both are used

### `dynamic_masks`
- status: doc-derived
- type: `array`
- required: Optional
- rules:
  - up to 6 groups
  - each group contains `mask` and `trajectories`
  - trajectory length for 5s video <= 77
  - coordinate count range `[2, 77]`
  - bottom-left image origin

#### Recoverable child fields
##### `dynamic_masks[].mask`
- type: `string`
- required: yes
- meaning: mask payload for one dynamic mask group

##### `dynamic_masks[].trajectories`
- type: `array`
- required: yes
- meaning: ordered motion path coordinates for one dynamic mask group
- constraints:
  - coordinate count range `[2, 77]`
  - trajectory length for 5s video <= 77
  - image origin is bottom-left

##### `dynamic_masks[].trajectories[].x`
- type: `int`
- required: yes
- meaning: x-coordinate for one trajectory point

##### `dynamic_masks[].trajectories[].y`
- type: `int`
- required: yes
- meaning: y-coordinate for one trajectory point

### `camera_control`
- status: doc-derived
- type: `object`
- required: Optional
- note: camera movement control object

#### Recoverable child fields
##### `camera_control.type`
- type: `string`
- required: conditional
- documented enum values:
  - `simple`
  - `down_back`
  - `forward_up`
  - `right_turn_forward`
  - `left_turn_forward`

##### `camera_control.config`
- type: `object`
- required: conditional
- rule: required when `type="simple"`
- constraint: choose only one non-zero field among `horizontal`, `vertical`, `pan`, `tilt`, `roll`, `zoom`
- value range for each supported field: `[-10, 10]`

### `duration`
- status: doc-derived + live-confirmed
- type: `string`
- required: Optional
- default: `5`
- enum values: `3` through `15`

### `watermark_info`
- status: doc-derived
- type: `object`
- required: Optional
- note: shaped as `{ "enabled": boolean }`

#### Recoverable child field
##### `watermark_info.enabled`
- type: `boolean`
- meaning: whether watermark generation is enabled for the task

### `callback_url`
- status: doc-derived
- type: `string`
- required: Optional

### `external_task_id`
- status: doc-derived + live-confirmed family usage
- type: `string`
- required: Optional
- rules:
  - custom task ID
  - does not overwrite system task ID
  - can be used for task queries
  - must be unique within one user account

### Scenario examples explicitly present
- `Image to video with multi-shot`
- `Image-to-video with voice of element`
- meaning: multi-shot and voice-of-element branches are both first-class documented subflows in preserved docs

---

# 8. Image to Video — Query Task (Single)

## Section status
- exact path/query selector and response-body rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__imageToVideo.txt`
- status: doc-derived
- live family query existence was already known; this pass closes the preserved row-level gap

## Exact query rows recovered from preserved docs
### Endpoint / path form
- rendered section title path: `GET /v1/videos/image2video/{id}`
- cURL example path: `GET /v1/videos/image2video/{task_id}`
- canonical interpretation for current docs: the path family is explicit and should be treated as correct; `{id}` should be read as a generic path placeholder, while the practical selector semantics are `task_id` or `external_task_id` as described in the preserved request rows
- current conclusion: this is a placeholder-label inconsistency in the preserved docs, not evidence of multiple different query route families

### Path/query selectors
#### `task_id`
- status: doc-derived
- type: `string`
- required: Optional
- meaning: task ID for image to video
- note: request path parameter; fill value directly in request path
- note: choose one between `task_id` and `external_task_id` for querying

#### `external_task_id`
- status: doc-derived
- type: `string`
- required: Optional
- meaning: customized task ID for image to video
- note: the `external_task_id` provided when creating the task
- note: choose one between `task_id` and `external_task_id` for querying

## Response body rows recovered from preserved docs
### Top-level envelope
- `code`
- `message`
- `request_id`
- `data`

### `data.task_id`
- status: doc-derived
- type: `string`
- meaning: task ID generated by the system

### `data.task_status`
- status: doc-derived
- type: `string`
- enum values: `submitted`, `processing`, `succeed`, `failed`

### `data.task_status_msg`
- status: doc-derived
- type: `string`
- meaning: failure/status information when task fails
- preserved note mentions platform content-risk-control as an example failure reason

### `data.watermark_info.enabled`
- status: doc-derived
- type: `boolean`

### `data.task_result.videos[]`
- status: doc-derived
- child rows recovered:
  - `id` — generated video ID; globally unique
  - `url` — generated video URL; preserved note says generated images/videos are cleared after 30 days, so save promptly
  - `watermark_url` — watermarked video download URL, anti-leech format
  - `duration` — total video duration, unit `s`

### `data.task_info.external_task_id`
- status: doc-derived
- type: `string`
- meaning: customer-defined task ID

### `data.final_unit_deduction`
- status: doc-derived
- type: `string`
- meaning: deduction units of task

### `data.created_at`
- status: doc-derived
- type: timestamp-like integer example
- meaning: Unix timestamp in `ms`

### `data.updated_at`
- status: doc-derived
- type: timestamp-like integer example
- meaning: Unix timestamp in `ms`

# 9. Image to Video — Query Task (List)

## Section status
- exact query parameters and response-body rows recovered from preserved artifact:
  - `samples/kling-api/deep-pages/apiReference_model__imageToVideo.txt`
- status: doc-derived

## Endpoint / query form
- path: `GET /v1/videos/image2video`
- preserved example: `GET /v1/videos/image2video?pageNum=1&pageSize=30`

## Query parameters
### `pageNum`
- status: doc-derived
- type: `int`
- required: Optional
- default: `1`
- meaning: page number
- range: `[1, 1000]`

### `pageSize`
- status: doc-derived
- type: `int`
- required: Optional
- default: `30`
- meaning: data volume per page
- range: `[1, 500]`

## Response body rows recovered from preserved docs
### Top-level envelope
- `code`
- `message`
- `request_id`
- `data[]`

### Per-item rows in `data[]`
- `task_id`
- `task_status` (`submitted|processing|succeed|failed`)
- `task_status_msg`
- `task_info.external_task_id`
- `task_result.videos[]`
  - `id`
  - `url`
  - `watermark_url`
  - `duration`
- `watermark_info.enabled`
- `final_unit_deduction`
- `created_at`
- `updated_at`

---

## Tier 1 gaps still remaining
This document is materially stronger now, but these items still remain:
- any deeper nested child-row cleanup for camera / mask / voice branches beyond the current core create/query coverage
- exact Text-to-Video `voice_list` row parity with the stronger Image-to-Video extraction
- path-placeholder semantics for Text/Image single-query pages remain slightly inconsistent in preserved docs (`{id}` section title vs `{task_id}` cURL example)

## Next Tier 1 documentation step
Continue preserved-artifact extraction focused on:
1. any nested branch rows that materially differ from the summarized create/query coverage above
2. Text-to-Video audio/voice parity cleanup
3. only then any remaining child-row polish that would materially reduce implementation ambiguity


## 2026-03-29 preserved deep-page breakthrough for Text/Image create rows
A targeted pass over overlooked preserved files under `samples/kling-api/deep-pages/` resolved the long-standing Tier 1 create-body gap:
- `apiReference_model__textToVideo.txt`
- `apiReference_model__imageToVideo.txt`

What changed:
- these preserved text extracts do contain the rendered `Create Task` request-body rows for both Text-to-Video and Image-to-Video
- they expose field names, type/required/default metadata, enum values, and inline constraint notes directly
- they also expose the documented create examples and multi-shot scenario examples

Interpretation:
- Text/Image create-body extraction is no longer blocked
- the remaining blocker has narrowed to query-response transcription and any deeper nested child-row cleanup still worth doing


## 2026-03-29 direct Qingque row extraction — Omni-Video Create Task
The preserved `samples/kling-api/qingque-deep/page.txt` contains explicit Omni-Video create-body rows. Newly confirmed doc-derived details:

### `model_name`
- type: string
- required: Optional
- default: `kling-video-o1`
- enum values: `kling-video-o1`, `kling-v3-omni`

### `multi_shot`
- type: boolean
- required: Optional
- default: `false`
- doc-derived rules:
  - `true` -> `prompt` parameter is invalid
  - `false` -> `shot_type` and `multi_prompt` are invalid

### `shot_type`
- type: string
- required: Optional
- default: `None`
- enum values: `customize`
- when `multi_shot=true`, current parameter is required

### `prompt`
- type: string
- required: Optional
- default: `None`
- additional doc-derived rules:
  - may include positive and negative descriptions
  - cannot exceed 2500 characters
  - when `multi_shot=false` or `shot_type=intelligence`, must not be empty
  - supports templating with `<<<element_1>>>`, `<<<image_1>>>`, `<<<video_1>>>`

### `multi_prompt[]`
- type: array
- required: Optional
- default: `None`
- doc-derived rules:
  - up to 6 storyboards, minimum 1 storyboard
  - each storyboard content max length 512
  - each storyboard duration >= 1
  - each storyboard duration must not exceed total task duration
  - sum of storyboard durations must equal total task duration
  - when `multi_shot=true` and `shot_type=customize`, this parameter must not be empty

### `image_list[]`
- type: array
- required: Optional
- default: `None`
- reference image list supports element/scene/style images and start/end frame use
- doc-derived rules:
  - `first_frame` = start frame
  - `end_frame` = end frame
  - end-frame-only is not supported; if there is an end frame, there must also be a first frame
  - when using first frame or first+last frame video generation, video editing functions cannot be used
  - supported image input: base64 or URL
  - supported formats: `.jpg`, `.jpeg`, `.png`
  - max file size: 10MB
  - width/height must each be >= 300px
  - aspect ratio must be between `1:2.5` and `2.5:1`
  - with reference video present: number(reference images) + number(reference elements) <= 4
  - with no reference video: number(reference images) + number(reference elements) <= 7
  - setting an end frame is not supported when there are more than 2 images
  - `image_url` must not be empty

### `element_list[]`
- type: array
- required: Optional
- default: `None`
- doc-derived rules:
  - based on element ID configuration
  - when using raw video from the first frame or first+last frames, a maximum of 3 subjects is supported
  - when there is a reference video: number(reference images) + number(reference subjects) <= 4, and the use of video subjects is not supported
  - when there is no reference video: number(reference images) + number(reference subjects) <= 7
  - elements are categorized into video customization elements (video character elements) and image customization elements (multi-image elements)

### `video_list[]`
- type: array
- required: Optional
- default: `None`
- doc-derived rules:
  - reference video or video to be edited
  - `refer_type=feature` -> feature reference video
  - `refer_type=base` -> video to be edited
  - when reference video is a video to be edited, start/end frames cannot be defined
  - `keep_original_sound=yes|no`
  - when there is a reference video, `sound` can only be `off`
  - only `.mp4` / `.mov`
  - only videos with duration >= 3s and <= 10s
  - video resolution width/height each between 720px and 2160px inclusive
  - only frame rates 24~60 fps supported; output result is 24 fps
  - only 1 video can be uploaded
  - max video size 200MB
  - `video_url` must not be empty

### `sound`
- type: string
- required: Optional
- default: `off`
- enum values: `on`, `off`
- doc-derived note: only V2.6 and subsequent versions support this parameter

### `mode`
- type: string
- required: Optional
- default: `pro`
- enum values: `std`, `pro`
- doc-derived meanings:
  - `std` -> Standard Mode, generates 720P videos, more cost-effective
  - `pro` -> Professional Mode, generates 1080P videos, higher-quality video output

### `aspect_ratio`
- type: string
- required: Optional
- default: `None`
- enum values: `16:9`, `9:16`, `1:1`
- doc-derived rule: required when first-frame reference or video editing features are not used

### `duration`
- type: string
- required: Optional
- default: `5`
- enum values: `3` through `15`
- doc-derived note: when using video editing (`refer_type=base`), output duration follows input video duration and current parameter is invalid; billing rounds input video duration to nearest integer


## 2026-03-29 extraction-method clarification after deep-page recovery
Earlier `qingque-deep/page.txt` and `page.html` passes were still insufficient for clean Text/Image create-row extraction.
That limitation is now better understood:
- `qingque-deep/*` was not the right preserved artifact for these two sections
- the overlooked successful artifacts were the dedicated deep-page text dumps:
  - `samples/kling-api/deep-pages/apiReference_model__textToVideo.txt`
  - `samples/kling-api/deep-pages/apiReference_model__imageToVideo.txt`

Interpretation:
- the previous blocker was artifact selection, not missing preserved content
- Omni remains best supported by `qingque-deep/page.txt` plus rendered HTML evidence
- Text/Image create-side extraction is now recovered from the dedicated deep-page dumps
- the remaining Tier 1 blocker is query-response transcription, not create-body discovery


## 2026-03-29 direct wording clarifications from preserved text
Additional preserved-text snippets reinforce these exact doc-derived readings for Omni-Video Create:
- the document spells the audio-retention field as `keep_original_sound` in the inline example, but nearby prose contains an apparent typo variant (`keep_original_stound`); treat the example field name `keep_original_sound` as canonical.
- `refer_type` explicitly distinguishes:
  - `feature` = feature reference video
  - `base` = video to be edited
- if a reference video exists, the `sound` parameter can only be `off`
- `mode` doc-derived default is `pro`
- `pro` is explicitly described as 1080P / higher-quality output
- `std` is explicitly described as 720P / cost-effective output