# Kling Qingque Full API Reference

Status: doc-derived source-of-truth transcription layer (Qingque-based) + selective live annotations
Source: Qingque captured artifact under `samples/kling-api/qingque-deep/`
Primary title observed in capture: `KlingAI Series 3.0 Model API Specification - 轻雀文档`
Captured: 2026-03-28 via Playwright deep extraction
Updated: 2026-03-29

## Purpose
This document promotes the Qingque Series 3.0 document to a full structured reference layer so future API work does not rely on partial notes or memory. It is intentionally more exhaustive than the prior summary notes.

## Source-of-truth policy
- Qingque document = doc-derived SOT for Series 3.0 structure and field naming
- Live API results = runtime truth for what actually works today
- When doc and live disagree:
  - keep both
  - mark the disagreement explicitly
  - do not silently overwrite doc-derived structure

## What was actually captured
Artifacts preserved under `samples/kling-api/qingque-deep/`:
- `page.html`
- `page.png`
- `headings.json`
- `anchors.json`
- `requests.json`

The captured corpus contains all of the following major sections confirmed by direct string search:
- Capability Map
- Video Generation
- Image Generation
- API
- Omni-Video - Create Task
- Omni-Video - Query Task (Single)
- Omni-Video - Query Task (List)
- Text to Video - Create Task
- Text to Video - Query Task (Single)
- Text to Video - Query Task (List)
- Image to Video - Create Task
- Image to Video - Query Task (Single)
- Image to Video - Query Task (List)
- Omni-Image - Create Task
- Omni-Image - Query Task (Single)
- Omni-Image - Query Task (List)
- Image Generation - Create task
- Image Generation - Query Task (Single)
- Image Generation - Query Task (List)
- General - Create Element
- General - Query Custom Element (Single)
- General - Query Custom Element (List)
- General - Query Presets Element (List)
- General - Delete Custom Element

---

## Capability Map (doc-derived)
The captured corpus confirms that the Qingque document includes capability-map sections covering:
- Video Generation
- Image Generation
- API

The document also includes invocation examples referenced by strings such as:
- Image-to-video with multi-shot
- Text-to-video with multi-shot
- Image-to-video with voice of element
- Image generation with element
- Create Multi-Image Elements
- Create Video Character Elements
- Query a specific custom entity
- List query of custom elements

---

## Omni-Video — Create Task

### Confirmed from captured Qingque text
The capture explicitly contains these request-body structures/fields:

#### `multi_prompt`
```json
"multi_prompt": [
  {
    "index": int,
    "prompt": "string",
    "duration": "5"
  },
  {
    "index": int,
    "prompt": "string",
    "duration": "5"
  }
]
```

#### `image_list`
```json
"image_list": [
  {
    "image_url": "image_url",
    "type": "first_frame"
  },
  {
    "image_url": "image_url",
    "type": "end_frame"
  }
]
```

#### Associated doc text observed in capture
- `image_list` is described as a reference image list
- `image_url` supports Base64 encoding or image URL (with accessibility requirement)
- `multi_shot=false`: `shot_type` and `multi_prompt` are invalid
- `shot_type=customize`: corresponding shot-configuration field must not be empty

### Current working request-body interpretation
For Omni image-guided generation, the strongest doc-derived request shape is:
```json
{
  "model_name": "kling-v3-omni",
  "prompt": "...",
  "duration": "5",
  "mode": "std",
  "aspect_ratio": "16:9",
  "image_list": [
    {
      "image_url": "<base64-or-url>",
      "type": "first_frame"
    }
  ]
}
```

### Live annotations
- Live confirmed: `image_list[].image_url + type='first_frame'` works and completes successfully
- Live rejected: `image_list[].image`
- Live rejected: `image_list[].image + index`
- Live confirmed: each `multi_prompt` entry needs `index` and `duration`

### 15-second continuity / context notes from SOT
Directly relevant SOT-visible knobs for longer contextual continuity are:
- `duration` up to 15s context in series-3 materials
- `multi_shot`
- `shot_type`
- `multi_prompt[]`
- `image_list[].type = first_frame | end_frame`

Important SOT reading:
- The document shows tools for structuring continuity and anchoring boundaries
- It does **not** (in the captured material we have reviewed so far) expose a single obvious dedicated flag like `maintain_context=true` or `keep_continuity=true`
- Therefore SOT currently points to continuity being achieved through composition of:
  - duration
  - shot sequencing
  - first/end frame anchoring
  - reference inputs
rather than a single continuity toggle

---

## Omni-Video — Query Task (Single)
The capture confirms this section exists and includes:
- Request Header
- Request Path Parameters
- Request Body
- Response Body

### Live alignment
- Single-task query path is real and working in live API use

---

## Omni-Video — Query Task (List)
The capture confirms this section exists and includes:
- Request Header
- Query Parameters
- Request Body
- Response Body

### Live alignment
- List-query structure existence is supported by both the capture and prior live work

---

## Text to Video — Create Task
Capture confirms section presence with:
- Request Header
- Request Body
- Response Body
- Invocation examples
- Text-to-video with multi-shot

### SOT relevance to continuity
- Text-to-video multi-shot exists in SOT
- therefore longer 15s narrative structuring is not Omni-only at the document level

### Live caution
- actual model support at runtime has shown drift from some early assumptions; keep live verification separate from doc structure

---

## Text to Video — Query Task (Single)
Capture confirms presence with:
- Request Header
- Request Path Parameters
- Request Body
- Response Body

## Text to Video — Query Task (List)
Capture confirms presence with:
- Request Header
- Query Parameters
- Request Body
- Response Body

---

## Image to Video — Create Task
Capture confirms presence with:
- Request Header
- Request Body
- Response Body
- Invocation examples
- Image-to-video with multi-shot
- Image-to-video with voice of element

### SOT relevance to continuity
This matters because the document suggests image-to-video is not merely a single still-to-motion path; it is also part of the multi-shot / element / voice ecosystem.

---

## Image to Video — Query Task (Single)
Capture confirms presence with:
- Request Header
- Request Path Parameters
- Request Body
- Response Body

## Image to Video — Query Task (List)
Capture confirms presence with:
- Request Header
- Query Parameters
- Request Body
- Response Body

---

## Omni-Image — Create Task
Capture confirms presence with:
- Request Header
- Request Body
- Response Body
- Invocation examples
- Image generation with element

## Omni-Image — Query Task (Single)
Capture confirms presence with:
- Request Header
- Request Path Parameters
- Request Body
- Response Body

## Omni-Image — Query Task (List)
Capture confirms presence with:
- Request Header
- Query Parameters
- Request Body
- Response Body

---

## Image Generation — Create Task
Capture confirms presence with:
- Request Header
- Request Body
- Response Body
- Invocation examples
- Image generation with element

## Image Generation — Query Task (Single)
Capture confirms presence with:
- Request Header
- Request Path Parameters
- Request Body
- Response Body

## Image Generation — Query Task (List)
Capture confirms presence with:
- Request Header
- Query Parameters
- Request Body
- Response Body

---

## General — Create Element
Capture confirms presence with:
- Request Header
- Request Body
- Response Body
- Invocation examples
- Create Multi-Image Elements
- Create Video Character Elements

### SOT implication
This is the strongest document-level signal that rich consistency / identity workflows may depend on explicit element creation rather than only inline request fields.

## General — Query Custom Element (Single)
Capture confirms presence with:
- Request Header
- Request Path Parameters
- Request Body
- Response Body
- Invocation examples
- Query a specific custom entity

## General — Query Custom Element (List)
Capture confirms presence with:
- Request Header
- Request Body
- Query Parameters
- Response Body
- Invocation examples
- List query of custom elements

## General — Query Presets Element (List)
Capture confirms presence with:
- Request Header
- Query Parameters
- Request Body
- Response Body

## General — Delete Custom Element
Capture confirms presence with:
- Request Header
- Request Body
- Response Body

---

## Direct answer: does SOT contain 15-second context/continuity-related content?
Yes — but mostly indirectly through composition controls, not through one obvious dedicated continuity switch.

### Present in SOT-derived capture
- 15-second generation positioning across Series 3 materials
- multi-shot support
- shot sequencing via `multi_prompt[]`
- explicit frame anchors via `image_list[].type = first_frame | end_frame`
- element-related APIs that likely support stronger subject continuity

### Not yet explicitly observed in the captured text we reviewed
- a dedicated single flag that literally means “maintain 15-second context continuity”
- a dedicated single flag that literally means “preserve video continuity”

### Best current SOT interpretation
Series 3 continuity appears to be designed as a structured-generation problem, achieved by combining:
- longer duration
- multi-shot planning
- frame anchoring
- element/reference control
rather than by flipping one standalone continuity option.

---

## What still needs transcription in more detail
This document upgrades Qingque into a fuller reference layer, but the next refinement step is still valuable:
- copy field tables section-by-section into more exact schema blocks
- extract more request/response examples verbatim where possible
- map each doc-derived field to live-confirmed / live-rejected / pending status

## Related docs
- `docs/current/kling-api-reference.md`
- `docs/current/kling-api-series-3-spec.md`
- `docs/current/kling-pipeline-action-items-from-blog-and-live-findings.md`
- `docs/current/kling-billable-create-guardrails.md`


## Additional SOT-extracted structures (2026-03-29)

### `video_list`
The Qingque capture also shows a video-reference structure:
```json
"video_list": [
  {
    "video_url": "video_url",
    "refer_type": "base",
    "keep_original_sound": "yes"
  }
]
```
Observed notes in capture:
- Only `.mp4` / `.mov` formats are supported

### `element_list`
The Qingque capture also shows an element-binding structure:
```json
"element_list": [
  {
    "element_id": long
  },
  {
    "element_id": long
  }
]
```
Interpretation:
- `video_list` likely carries video reference continuity / conditioning
- `element_list` likely carries reusable bound assets created through the General Element APIs