# Kling 3.0 API

쾌수(Kuaishou)의 Kling 3.0 동영상 생성 모델에 대한 완전한 API 레퍼런스.

## 모델 변형

이 API는 네 가지 모델 변형을 지원합니다:

| 모델 | ID | 등급 | 설명 |
|-------|-----|------|-------------|
| **Kling 3.0 Std Text to Video** | `kling-v3.0-std-text-to-video` | 스탠다드 | 스탠다드 품질의 텍스트 기반 동영상 생성 |
| **Kling 3.0 Std Image to Video** | `kling-v3.0-std-image-to-video` | 스탠다드 | 스탠다드 품질의 이미지 기반 동영상 애니메이션 |
| **Kling 3.0 Pro Text to Video** | `kling-v3.0-pro-text-to-video` | 프로 | 프로 품질의 텍스트 기반 동영상 생성 |
| **Kling 3.0 Pro Image to Video** | `kling-v3.0-pro-image-to-video` | 프로 | 프로 품질의 이미지 기반 동영상 애니메이션 |

## 빠른 비교

| 기능 | 스탠다드 | 프로 |
|---------|-----|-----|
| 품질 | 스탠다드 | 최고 |
| 생성 속도 | 빠름 | 느림 |
| 화면 비율 | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 |
| 길이 범위 | 3~15초 | 3~15초 |

| 기능 | 텍스트 기반 동영상 | 이미지 기반 동영상 |
|---------|---------------|----------------|
| 입력 | 텍스트 프롬프트 | 이미지 + 텍스트 프롬프트 |
| 시작 프레임 | 미지원 | 필수 |
| 종료 프레임 | 미지원 | 미지원 |
| 오디오 | 선택 사항 | 선택 사항 |

### 지원 화면 비율

| 비율 | 설명 |
|-------|-------------|
| `16:9` | 가로형 (와이드스크린) |
| `9:16` | 세로형 (포트레이트) |
| `1:1` | 정사각형 |

## Kling 3.0 텍스트 기반 동영상 (스탠다드 & 프로)

### 엔드포인트

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

### 요청 파라미터

#### 필수

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"kling-v3.0-std-text-to-video"` 또는 `"kling-v3.0-pro-text-to-video"` |
| `prompt` | string | 동영상 생성 프롬프트 |
| `duration` | number | 동영상 길이(초) (3~15) |
| `aspect_ratio` | string | 동영상 화면 비율: `"16:9"`, `"9:16"`, 또는 `"1:1"` |

#### 선택 사항

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `sound` | boolean | 동영상에 환경음 생성 |
| `guidance_scale` | number | 프롬프트 준수 강도, 0~1 사이의 부동소수점 |
| `negative_prompt` | string | 생성 동영상에서 제외할 요소 |

### 요청 예시

**스탠다드 버전:**

```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-v3.0-std-text-to-video',
    prompt: 'A fox running through a snowy forest at dusk',
    duration: 5,
    aspect_ratio: '16:9'
  })
});

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

**프로 버전:**

```javascript
{
  model_name: 'kling-v3.0-pro-text-to-video',
  prompt: 'A fox running through a snowy forest at dusk',
  duration: 5,
  aspect_ratio: '16:9'
}
```

## Kling 3.0 이미지 기반 동영상 (스탠다드 & 프로)

### 요청 파라미터

#### 필수

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"kling-v3.0-std-image-to-video"` 또는 `"kling-v3.0-pro-image-to-video"` |
| `prompt` | string | 동영상 생성 프롬프트 |
| `duration` | number | 동영상 길이(초) (3~15) |
| `aspect_ratio` | string | 동영상 화면 비율: `"16:9"`, `"9:16"`, 또는 `"1:1"` |
| `image_url` | string | 동영상의 첫 번째 프레임 이미지 |

#### 선택 사항

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `sound` | boolean | 동영상에 환경음 생성 |
| `guidance_scale` | number | 프롬프트 준수 강도, 0~1 사이의 부동소수점 |
| `negative_prompt` | string | 생성 동영상에서 제외할 요소 |

### 요청 예시

**스탠다드 버전:**

```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-v3.0-std-image-to-video',
    image_url: 'https://example.com/image.jpg',
    prompt: 'Gentle breeze, leaves rustling, slow camera pull back',
    duration: 5,
    aspect_ratio: '16:9'
  })
});

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

**프로 버전:**

```javascript
{
  model_name: 'kling-v3.0-pro-image-to-video',
  image_url: 'https://example.com/image.jpg',
  prompt: 'Gentle breeze, leaves rustling, slow camera pull back',
  duration: 5,
  aspect_ratio: '16:9'
}
```

## 응답 형식

### 초기 응답

```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/{taskId}` 를 폴링하여 상태 확인:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "task_result": {
      "credit": 0.2,
      "videos": [
        {
          "url": "https://example.com/generated-video.mp4"
        }
      ]
    }
  }
}
```

### 상태 값

- `submitted`: 작업이 수락되어 처리 대기 중입니다
- `processing`: 동영상 생성 중
- `succeed`: 동영상 생성 완료
- `failed`: 동영상 생성 실패

## 처리 시간

- **스탠다드 버전**: 길이에 따라 약 2~4분
- **프로 버전**: 길이에 따라 약 3~6분

5~10초마다 폴링하세요. 긴 동영상(10~15초)은 추가 시간이 필요할 수 있습니다.

## 모범 사례

1. **동작을 명확하게 묘사하기**: 더 역동적인 결과를 위해 프롬프트에 카메라 움직임과 피사체 동작을 포함하세요
2. **네거티브 프롬프트 활용하기**: 원하지 않는 요소(예: `"blurry, low quality, watermark"`)를 제외하여 출력 품질을 향상시키세요
3. **가이던스 스케일**: 낮은 값(0.3~0.5)은 더 많은 창의적 자유를 허용하고, 높은 값(0.7~1.0)은 프롬프트를 더 엄격하게 따릅니다
4. **이미지 품질**: 이미지 기반 동영상의 경우, 최상의 모션 품질을 위해 선명하고 밝은 입력 이미지를 사용하세요
5. **길이 선택**: 짧은 길이(3~5초)로 시작하여 빠르게 반복한 후 최종 출력에서 늘리세요
6. **등급 선택**: 빠른 반복에는 스탠다드 버전을, 최종 프로덕션 품질 동영상에는 프로 버전을 사용하세요