# Kling 3.0 Motion Control API

Kuaishou의 Kling 3.0 Motion Control 동영상 생성을 위한 전체 API 참조 문서입니다.

## 모델 종류

이 API는 한 가지 모델을 지원합니다.

| 모델 | ID | 설명 |
|-------|-----|-------------|
| **Kling 3.0 Motion Control** | `kling-3.0-motion-control` | 텍스트 프롬프트, 참조 이미지 한 장, 참조 동영상 한 개를 사용한 동영상 생성 |

## Kling 3.0 Motion Control

### 엔드포인트

```
POST /api/v1/video/task
```

### 요청 매개변수

#### 필수

| 매개변수 | 타입 | 설명 |
|-----------|------|-------------|
| `model_name` | string | 반드시 `"kling-3.0-motion-control"`이어야 합니다 |
| `prompt` | string | 동영상 생성 프롬프트, 최대 5000자 |
| `images` | string[] | 참조 이미지 URL을 정확히 하나 지정합니다. `.jpg`, `.jpeg`, `.png`를 지원하며, 파일 크기는 50 MB 이하여야 합니다. 너비와 높이는 각각 300 px 이상이어야 하며, 이미지 종횡비는 1:2.5에서 2.5:1 사이여야 합니다 |
| `videos` | string[] | 참조 동영상 URL을 정확히 하나 지정합니다. `.mp4`와 `.mov`를 지원하며, 파일 크기는 100 MB 이하여야 합니다. 너비와 높이는 각각 340 px 이상 3850 px 이하여야 합니다. 길이는 최소 3초이며, 최대 길이는 `character_orientation`에 따라 달라집니다 |
| `character_orientation` | string | 필수이며 기본값이 없습니다. `"image"`: 참조 이미지 속 캐릭터의 방향을 따르며, 참조 동영상은 3~10초여야 합니다. `"video"`: 참조 동영상 속 캐릭터의 방향을 따르며, 참조 동영상은 3~30초여야 합니다. 두 길이 범위 모두 양 끝값을 포함합니다 |
| `resolution` | string | 출력 해상도: `"720p"` 또는 `"1080p"`. 필수이며 기본값이 없습니다 |

#### 선택

| 매개변수 | 타입 | 설명 |
|-----------|------|-------------|
| `keep_original_sound` | boolean | 참조 동영상의 원본 소리를 유지할지 여부입니다. `true` 또는 `false`를 허용하며, 기본값은 `true`입니다 |

출력 길이는 원본 동영상의 길이를 따릅니다. `duration` 매개변수는 지원되지 않습니다. 출력 종횡비는 입력 미디어에 따라 결정되며, `aspect_ratio`는 지원되지 않습니다. 상위 제공업체는 어떤 입력이 출력 종횡비를 결정하는지 또는 정확한 선택 규칙을 명시하지 않았습니다.

요금은 원본 동영상의 길이를 가장 가까운 정수 초로 반올림한 값과 선택한 출력 해상도를 기준으로 계산됩니다. 예를 들어 5.4초는 5초로, 5.5초는 6초로 청구됩니다.

### 요청 예제

예제 미디어 URL을 위 요구사항을 충족하는 본인의 파일 URL로 바꾸세요.

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'kling-3.0-motion-control',
    prompt: 'Animate the character in the reference image using the dance movements from the reference video',
    images: ['https://example.com/character.jpg'],
    videos: ['https://example.com/dance-reference.mp4'],
    character_orientation: 'video',
    resolution: '720p',
    keep_original_sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## 응답 형식

### 초기 응답

폴링에 사용할 `task_id`를 반환합니다.

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "submitted"
  }
}
```

`GET /api/v1/video/{task_id}`로 폴링하여 상태를 확인하고 생성된 동영상을 가져옵니다.

### 상태 값

- `submitted`: 작업이 접수되어 처리를 기다리는 중
- `processing`: 동영상 생성 중
- `succeed`: 동영상 생성 완료
- `failed`: 동영상 생성 실패

## 권장 사항

1. **참조 미디어**: 이미지 한 장과 동영상 한 개를 정확히 제공하고, 제출 전에 형식, 파일 크기, 너비와 높이를 확인하세요
2. **방향**: `character_orientation`을 변경할 때, 특히 `"image"`를 선택할 경우 참조 동영상의 길이를 다시 확인하세요
3. **원본 소리**: 참조 동영상의 원본 소리를 유지하지 않으려면 `keep_original_sound`를 `false`로 설정하세요. 생략하면 소리가 유지됩니다