# Kling implementation handoff Status: active handoff note Captured: 2026-03-29 ## Purpose Provide a practical handoff for the next implementation phase so that someone can resume work from the documentation set without re-deriving the current direction. --- # 1. Current top-level strategy ## Priority order 1. Documentation first 2. Code sync second 3. Live verification later ## Pipeline policy - one scene = one clip - single-scene ceiling = 15s - multi-clip chaining is for cross-scene continuity, not for simulating one hidden continuous scene ## Cost policy - every create is billable - first success ends probing - SOT must be consulted before any new payload shape is tried live --- # 2. Current most important reference paths ## Current production-facing route scope Use these as the active production layer: - `text2video` with `kling-v3` - `image2video` with `kling-v3` - `omni` with `kling-v3-omni` ## Image-anchored one-scene path Use: - `image_list[].image_url + type='first_frame'` - optional `end_frame` Hard limits that must stay visible in implementation: - with no reference video: `reference images + reference elements <= 7` - with reference video: `reference images + reference elements <= 4` - `end_frame` is not supported when there are more than 2 images ## Scene-to-scene continuation path Use: - `video_list[].video_url=` - `refer_type='base'` - `keep_original_sound='yes'` ## Future strongest identity path Use directionally: - `element_list[].element_id` - backed by General / Create Element workflows once exact schemas are more fully extracted ## Which path to use for which purpose - **Need one reference-guided scene now** -> Omni `image_list[].image_url` - **Need one generated clip with multiple storyboarded beats** -> Omni `multi_shot` + `multi_prompt[]` - **Need recurring characters/assets reused across many scenes** -> Elements workflow + `element_list[].element_id` - **Need continuity from one finished clip into the next clip** -> `video_list` continuation / remote video reference - **Need to continue the same clip longer** -> no current-production route confirmed in the active route set Implementation reading: - `video_list` and `element_list` can be complementary - `video_list` carries previous clip context - `element_list` carries recurring identity/assets - exact extension should not be delegated to `video_list`; historical `video-extend` exists in the broader docs corpus, but it is legacy/non-current for this repo ## Legacy/non-current handling rule - do not pull broader docs-corpus routes back into the current production layer casually - routes like `reference2video` should remain historical/legacy unless fresh current-3.0 evidence changes that status --- # 3. What is already safe to rely on - Omni endpoint path exists and works - `multi_prompt[]` structure is real - Omni `image_list[].image_url + type` works - Omni `video_list[].video_url=` works - top-level guessed legacy patterns have been identified and deprecated - documentation roles are now clearly separated --- # 4. What is still not tight enough to implement blindly - broad non-Omni endpoint-wide code sync without a deliberate product/model decision - full audio / native voice semantics beyond the preserved `voice_list` and prompt-tag patterns - capability-map-dependent support edges (`4k`, `series`, version/model support ranges) - residual path/selector ambiguities like `{id}` vs `{task_id}` where preserved docs disagree - deeper nested child validation beyond the currently recovered field-level coverage - mixed-generation routes that still appear in the broader docs corpus but are no longer considered current production choices --- # 5. What to read first before doing anything 1. `kling-billable-create-guardrails.md` 2. `kling-api-field-status-register.md` 3. relevant tier field-level doc 4. `kling-api-reference.md` 5. `kling-qingque-full-api-reference.md` 6. blog notes only afterward for workflow hints --- # 6. What to do next in documentation ## Documentation follow-up (non-blocking refinement) - polish deeper nested child rows where preserved artifacts expose structure but not perfect standalone tables - keep audio/native voice semantics explicitly bounded to what is source-grounded - keep gap/status/progress docs aligned when later live verification changes confidence ## Keep updating - field status register - gap log - approved payload patterns - progress board --- # 7. What to do next in code (after docs are tighter) - start with Omni-first builders/validators/defaults alignment - keep Omni helpers opinionated only where the narrowed sync is actually safe - avoid broad non-Omni endpoint sync until model policy is explicitly decided - for non-Omni endpoints, prefer no silent model default over a misleading “safe” default - quarantine deprecated helper paths - annotate code with doc-derived vs live-confirmed distinctions where useful --- # 8. What the next live verification should eventually be Only after docs are tighter enough: 1. `pro` mode quality comparison 2. stronger `video_list(remote url)` continuation check with a more deliberate prompt 3. element-backed generation 4. audio / voice workflow validation --- ## Bottom line The project now has enough structure to stop improvising. The next correct move is not more random testing; it is to keep tightening the field-level documentation until implementation can proceed safely.