# Kling API Series 3.0 Detailed Specification

> **Doc maintenance:** This file is indexed in `docs/current/README.md`. If you change this file's role, scope, status, or filename, update `docs/current/README.md` in the same edit.


작성: 2026-03-28  
상태: **working deep-dive**

## 문서 성격
이 문서는 Kling 메인 API 문서와 별도로, `KlingAI Series 3.0 Model API Specification` Qingque 문서에서 확보한 내용을 정리한 **3.0 계열 상세 스펙 문서**다.

이 문서는 전체 통합 문서를 대체하지 않는다.  
역할은 다음과 같다:
- 3.0 계열 capability map 보강
- 3.0 모델 enum 확인
- Create Task / Query(Single/List) 구조 확인
- multi-shot / element / image/video capability 차이 정리

## 소스
- 추출 제목: `KlingAI Series 3.0 Model API Specification - 轻雀文档`
- 추출 경로: `youtube-automation/samples/kling-api/qingque-deep/page.txt`
- 신뢰도: **공식 문서 UI에서 연결된 보조 상세 스펙 문서로 매우 유력**

---

## 1. 핵심 확인 사항

### 1.1 문서 구조
확인된 주요 섹션:
- 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 / Query Task (Single/List)
- Image to Video - Create Task / Query Task (Single/List)
- Omni-Image - Create Task / Query Task (Single/List)
- Image Generation - Create Task / Query Task (Single/List)
- General - Create Element / Query / Delete
- Prepaid Resource Packs

### 1.2 가장 중요한 새 정보
- `KlingAI Series 3.0 Model API Specification` 본문 확보 성공
- `Omni-Video` create endpoint 확인: `POST /v1/videos/omni-video`
- Omni 관련 model enum에 `kling-v3-omni` 확인
- Text / Image / Omni-Image / Image Generation 계열에 대해 **Create + Query(Single/List)** 구조 존재 확인
- Capability Map에서 3.0 모델 계열 차이 확인

---

## 2. Capability Map 요약

### 2.1 Video
#### text to video
- single-shot video generation: ✅
- multi-shot video generation: ✅
- voice control: ❌

#### image to video
- single-shot video generation (only start frame): ✅
- multi-shot video generation: ✅
- start & end frame: ✅
- element control (video character elements & multi-image elements): ✅
- motion control: **coming soon**
- voice control: ❌

### 2.2 Image
#### `kling-v3-omni`
- custom aspect ratio: 1K / 2K / 4K
- intelligent aspect ratio
- text to image: single-image generation ✅
- image to image: single-image generation ✅
- series-image generation ✅
- element control (only multi-image elements) ✅

#### `kling-image-o1`
- custom aspect ratio: 1K / 2K
- intelligent aspect ratio
- text to image: single-image generation ✅
- image to image: single-image generation ✅
- element control ✅

#### `kling-v3`
- custom aspect ratio: 1K / 2K
- intelligent aspect ratio
- text to image: single-image generation ✅
- image to image: single-image generation ✅ (본문 추출 특성상 세부 표는 재확인 가치 있음)
- element control ✅

---

## 3. Omni-Video 상세

### 3.1 Create Task
```http
POST /v1/videos/omni-video
```

### 3.2 확인된 Request Header
- `Content-Type: application/json`
- `Authorization: Authentication information, refer to API authentication`

### 3.3 확인된 Request Body 핵심 필드
- `model_name`
  - enum: `kling-video-o1`, `kling-v3-omni`
- `multi_shot`
  - `true`이면 `prompt` 무효, `shot_type` / `multi_prompt` 쪽 요구됨
  - `false`이면 `shot_type` / `multi_prompt` 무효
- `shot_type`
  - enum: `customize`
  - `multi_shot=true`일 때 필요
- `prompt`

### 3.4 의미
- 3.0 계열에서 multi-shot이 단순 예시 수준이 아니라 **API contract 상의 실제 분기 필드**로 들어간다는 점이 중요하다.
- 기존 메인 문서보다 3.0 쪽 storyboarding/multi-shot 해석을 더 구체화할 수 있다.

---

## 4. Query 구조

이 문서에서 가장 중요한 보강점 중 하나는, 각 주요 capability에 대해 단순 Create Task만이 아니라 아래 구조가 같이 보인다는 점이다.

### 확인된 패턴
- `Create Task`
- `Query Task (Single)`
- `Query Task (List)`

### 현재 확인된 capability
- Omni-Video
- Text to Video
- Image to Video
- Omni-Image
- Image Generation
- General / Custom Elements

### 의미
- 기존 스캐폴드의 generic query helper는 방향은 맞았지만, 실제 구현은 capability별 공식 query path를 이 문서 기준으로 더 정교하게 고정해야 한다.
- callback-first는 유지하되, fallback polling도 정식 endpoint 체계 위에서 다시 설계할 수 있다.

---

## 5. 파이프라인에 주는 영향

### 바로 영향 주는 것
1. `kling-v3-omni`를 실제 model enum 후보로 반영 가능
2. multi-shot은 단순 아이디어가 아니라 계약 레벨 capability로 봐야 함
3. Query Single/List 계층을 코드 구조에 반영해야 함
4. image-to-video에서 start & end frame / element control 차이를 고려해야 함

### 아직 주의할 것
- 본문은 확보됐지만 field-level contract 전체를 완전히 표로 정리한 상태는 아님
- capability matrix와 API body 표를 더 정밀하게 후속 추출/정리할 가치가 큼
- Qingque 문서는 3.0 중심 문서이므로, 전체 Kling 통합 문서와 역할을 분리해 유지해야 함

---

## 6. 현재 권고
- 이 문서는 `kling-api-reference.md`의 하위 보조 상세 스펙으로 유지
- 구현 직전에는 이 문서 기준으로 다음을 다시 고정:
  - 3.0 model enum
  - multi-shot 관련 필드
  - Query Single/List path
  - image-to-video advanced options

---

## 7. 후속 보강 포인트
- Qingque 본문에서 endpoint path와 field 표를 섹션 단위로 재절단 추출
- Query(Single/List) 실제 path 확정
- Text to Video / Image to Video / Omni-Image / Image Generation 각 body field 표 정리
- `General - Create Element` 계열이 메인 파이프라인에 어떻게 연결되는지 재평가


---

## 8. live smoke test correction

Series 3.0 문서 추출상 `mode` 설명은 `std` / `pro` enum을 시사했고, 2026-03-29 실 API smoke test로 실제로 확인됐다.

- `mode='standard'` → 실패 (`1201`, invalid)
- `mode='std'` → 성공

따라서 3.0 구현 시 `mode`는 반드시 `std` / `pro`로 취급한다.


## 9. Multi-endpoint smoke sequence note
- text2video: model kling-video-o1 not supported
- text2video: model kling-v3-omni not supported
- image2video: model kling-v3-omni not supported
- image2video: model kling-video-o1 not supported
- reference2video: request body shape still mismatched for current variant


## 2026-03-29 contract refinements from deeper live probing
- image2video_img256_png: failed (Image pixel is invalid)
- image2video_img512_png: submitted ()
- image2video_img512_jpg: submitted ()
- reference2video_img256_png: processing ()
- reference2video_img512_png: processing ()
- reference2video_img512_jpg: processing ()
- omni_multishot_probe_3: create/query succeeded after adding index fields to multi_prompt
- omni_multishot_probe_3: create/query succeeded after adding index fields to multi_prompt

## 2026-03-29 live update — Omni image input shape
- Based on live probing, Omni image conditioning is currently best modeled as `image_list[].image_url` with explicit frame role types such as `first_frame`.
- `image_list[].image` was rejected live with request-body resolution failure.
- This makes the screenshot/document example materially stronger than our earlier provisional `image_list[].image` assumption.