# Kling API field-level audit plan

Status: active documentation task
Captured: 2026-03-29

## Goal
Complete a field-level transcription and audit of the Qingque-derived Series 3 API so pipeline code no longer depends on partial payload memory or improvised field guesses.

## Why this is now priority #1
Recent failures were not caused by lack of source material. They were caused by not translating available SOT details into field-level docs and code rigorously enough.

## Scope
The audit should cover the full Qingque-derived API reference surface, with special attention to nested request-body structures and conditional rules.

---

## Required output format for each endpoint
For every endpoint or API section, document:

1. Section / endpoint name
2. Purpose
3. Request Header
4. Request Path / Query Parameters
5. Request Body (field-by-field)
   - field name
   - type
   - required / optional
   - enum values when visible
   - nested object shape when applicable
   - conditions / invalid combinations when visible
6. Response Body (field-by-field when practical)
7. Invocation examples
8. Status tags per field:
   - doc-derived
   - live-confirmed
   - live-rejected
   - hypothesis-only
9. Notes on cost / quality / continuity relevance if applicable

---

## Priority endpoint order

### Tier 1 — immediate pipeline-critical
1. Omni-Video — Create Task
2. Omni-Video — Query Task (Single)
3. Omni-Video — Query Task (List)
4. Text to Video — Create Task
5. Text to Video — Query Task (Single)
6. Text to Video — Query Task (List)
7. Image to Video — Create Task
8. Image to Video — Query Task (Single)
9. Image to Video — Query Task (List)

### Tier 2 — next-step continuity/identity critical
10. General — Create Element
11. General — Query Custom Element (Single)
12. General — Query Custom Element (List)
13. General — Query Presets Element (List)
14. General — Delete Custom Element

### Tier 3 — image-generation / broader parity
15. Omni-Image — Create Task
16. Omni-Image — Query Task (Single)
17. Omni-Image — Query Task (List)
18. Image Generation — Create Task
19. Image Generation — Query Task (Single)
20. Image Generation — Query Task (List)

---

## Field clusters that must be explicitly audited

### Omni / video generation structures
- `multi_shot`
- `shot_type`
- `multi_prompt[]`
- `image_list[]`
- `video_list[]`
- `element_list[]`
- `mode`
- duration limits / options
- quality/professional-mode mentions

### Element / identity structures
- create-element request fields
- multi-image element fields
- video character element fields
- asset IDs / `element_id`
- query/list/delete shapes

### Audio / voice structures
- `voice_list`
- voice tag syntax references
- audio-binding inputs
- `keep_original_sound`
- any audio-specific flags or modes

---

## Non-negotiable documentation rules
1. Do not compress nested fields into vague prose if the captured doc shows structure explicitly.
2. If a field appears in SOT, include it by exact name.
3. If a field is only inferred, mark it as hypothesis-only.
4. If live API rejects a field, keep it documented with a rejected note instead of silently deleting history.
5. If doc and live differ, document both and label the conflict.

---

## Required follow-up after docs are complete
1. Compare builder outputs against doc-derived schemas
2. Compare validator allowlists against doc-derived fields
3. Flag any code path still using guessed field names
4. Create a shortlist of safe next live verifications using only doc-grounded payloads

---

## Immediate success condition
This task is considered successful when a future API implementation question can be answered from the field-level docs directly, without needing to reopen the raw Qingque capture or guess nested payload shapes.