# Kling 3.0 Motion Control API

เอกสารอ้างอิง API ฉบับสมบูรณ์สำหรับการสร้างวิดีโอด้วย Kling 3.0 Motion Control ของ Kuaishou

## รุ่นของโมเดล

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 ถึง 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` เพื่อไม่เก็บเสียงต้นฉบับของวิดีโออ้างอิง หากไม่ระบุพารามิเตอร์นี้จะเก็บเสียงไว้