# Seedance 2.5 API

เอกสารอ้างอิง API ฉบับสมบูรณ์สำหรับโมเดลสร้างวิดีโอ Seedance 2.5 ของ ByteDance

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

API นี้รองรับโมเดลสามรุ่น:

| โมเดล | ID | คำอธิบาย |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | สร้างวิดีโอคุณภาพสูงจากข้อความ |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | สร้างวิดีโอจากเฟรมแรก หรือจากเฟรมแรกและเฟรมสุดท้าย |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | สร้างวิดีโอโดยใช้ภาพ วิดีโอ และเสียงอ้างอิงเป็นแนวทาง |

## เปรียบเทียบโดยย่อ

| คุณสมบัติ | ข้อความเป็นวิดีโอ | ภาพเป็นวิดีโอ | สื่ออ้างอิงเป็นวิดีโอ |
|---------|---------------|----------------|--------------------|
| ช่วงความยาว | 4-30 วินาที | 4-30 วินาที | 4-30 วินาที |
| ตัวเลือกความละเอียด | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| อัตราส่วนภาพ | จำเป็น | ไม่รองรับ | จำเป็น |
| สื่อที่จำเป็น | ไม่มี | ภาพเฟรมแรก | ไม่มี |
| สื่อเพิ่มเติม | ไม่มี | ภาพเฟรมสุดท้าย | ภาพ วิดีโอ และเสียง |

### อัตราส่วนภาพที่รองรับ

ข้อความเป็นวิดีโอและสื่ออ้างอิงเป็นวิดีโอรองรับ:

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

ภาพเป็นวิดีโอไม่รองรับพารามิเตอร์ `aspect_ratio`

### ตัวเลือกความละเอียด

| ความละเอียด | คำอธิบาย |
|------------|-------------|
| `480p` | ความคมชัดมาตรฐาน |
| `720p` | ความคมชัดสูง |
| `1080p` | Full HD |

## Seedance 2.5 Text to Video

### ปลายทาง API

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

### พารามิเตอร์คำขอ

#### จำเป็น

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `model_name` | string | ต้องเป็น `"seedance-v2.5-text-to-video"` |
| `prompt` | string | พรอมต์สำหรับสร้างวิดีโอ |
| `resolution` | string | ความละเอียดผลลัพธ์: `"480p"`, `"720p"` หรือ `"1080p"` |
| `duration` | integer | ความยาววิดีโอเป็นจำนวนเต็มวินาที (4-30) เพิ่มครั้งละ 1 วินาที |
| `aspect_ratio` | string | อัตราส่วนภาพวิดีโอ: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` หรือ `"3:4"` |

#### ไม่บังคับ

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `sound` | boolean | กำหนดว่าจะสร้างเสียงหรือไม่ ค่าเริ่มต้นคือ `true` |

### ตัวอย่างคำขอ

```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: 'seedance-v2.5-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    resolution: '720p',
    duration: 8,
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.5 Image to Video

### พารามิเตอร์คำขอ

#### จำเป็น

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `model_name` | string | ต้องเป็น `"seedance-v2.5-image-to-video"` |
| `prompt` | string | พรอมต์สำหรับสร้างวิดีโอ |
| `resolution` | string | ความละเอียดผลลัพธ์: `"480p"`, `"720p"` หรือ `"1080p"` |
| `duration` | integer | ความยาววิดีโอเป็นจำนวนเต็มวินาที (4-30) เพิ่มครั้งละ 1 วินาที |
| `image_url` | string | URL ภาพเฟรมแรก |

#### ไม่บังคับ

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `image_end_url` | string | URL ภาพเฟรมสุดท้ายที่ไม่บังคับ |
| `sound` | boolean | กำหนดว่าจะสร้างเสียงหรือไม่ ค่าเริ่มต้นคือ `true` |

> อย่าใส่ `aspect_ratio` ในคำขอภาพเป็นวิดีโอ โมเดลนี้ไม่รองรับพารามิเตอร์ดังกล่าว

### ตัวอย่างคำขอ

```javascript
{
  model_name: 'seedance-v2.5-image-to-video',
  image_url: 'https://example.com/first-frame.jpg',
  image_end_url: 'https://example.com/last-frame.jpg',
  prompt: 'Camera slowly pulls back to reveal the full landscape',
  resolution: '720p',
  duration: 8,
  sound: true
}
```

## Seedance 2.5 Reference to Video

### พารามิเตอร์คำขอ

#### จำเป็น

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `model_name` | string | ต้องเป็น `"seedance-v2.5-reference-to-video"` |
| `prompt` | string | พรอมต์สำหรับสร้างวิดีโอ เขียนพรอมต์ทั่วไปโดยไม่ใช้ตัวแทนค่า หรือเลือกใช้ฟีเจอร์อ้างอิง @ (AT) พร้อม `<<<image_N>>>`, `<<<video_N>>>` และ `<<<audio_N>>>` เพื่ออ้างถึงรายการในอาร์เรย์สื่อที่เกี่ยวข้องอย่างชัดเจน |
| `resolution` | string | ความละเอียดผลลัพธ์: `"480p"`, `"720p"` หรือ `"1080p"` |
| `duration` | integer | ความยาววิดีโอเป็นจำนวนเต็มวินาที (4-30) เพิ่มครั้งละ 1 วินาที |
| `aspect_ratio` | string | อัตราส่วนภาพวิดีโอ: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` หรือ `"3:4"` |

#### สื่ออ้างอิง

สื่ออ้างอิงทั้งหมดไม่บังคับ รองรับคำขอที่มีเฉพาะภาพ เฉพาะวิดีโอ เฉพาะเสียง และไม่มีสื่ออ้างอิง หากสร้างโดยไม่มีสื่ออ้างอิง แนะนำให้ใช้ข้อความเป็นวิดีโอ

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `images` | string[] | URL ภาพอ้างอิง 0-30 รายการ ดูข้อจำกัดสื่อด้านล่าง |
| `videos` | string[] | URL วิดีโออ้างอิงรูปแบบ MP4 หรือ MOV จำนวน 0-10 รายการ แต่ละวิดีโอต้องยาว 2-30 วินาที โดยความยาวรวมไม่เกิน 30 วินาที |
| `audios` | string[] | URL เสียงอ้างอิงรูปแบบ WAV หรือ MP3 จำนวน 0-10 รายการ แต่ละรายการต้องยาว 2-30 วินาทีและมีขนาดไม่เกิน 15 MB โดยความยาวรวมไม่เกิน 30 วินาที |

#### ตัวแทนค่าอ้างอิง @ (AT)

ฟีเจอร์อ้างอิง @ (AT) เชื่อมสื่ออ้างอิงเข้ากับพรอมต์ผ่านตัวแทนค่า `<<<...>>>` ที่มีหมายเลข โดยนับจาก `1` แยกกันสำหรับสื่อแต่ละประเภท และเรียงตามลำดับในอาร์เรย์ที่เกี่ยวข้อง:

| ตัวแทนค่า | ค่าที่อ้างอิง |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

ตัวอย่างเช่น หากภาพแรกเป็นภาพอ้างอิงตัวละครและภาพที่สองเป็นภาพอ้างอิงฉาก ให้ใช้ `<<<image_1>>>` สำหรับตัวละครและ `<<<image_2>>>` สำหรับฉากใน `prompt` ตัวแทนค่าแต่ละตัวต้องชี้ไปยังรายการที่มีอยู่จริงในอาร์เรย์ที่เกี่ยวข้อง

#### ไม่บังคับ

| พารามิเตอร์ | ชนิด | คำอธิบาย |
|-----------|------|-------------|
| `sound` | boolean | กำหนดว่าจะสร้างเสียงหรือไม่ ค่าเริ่มต้นคือ `true` |

### ตัวอย่างคำขอ

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere',
  resolution: '720p',
  duration: 8,
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/subject-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/atmosphere-reference.mp3']
}
```

### ตัวอย่างคำขอสื่ออ้างอิงเป็นวิดีโอด้วย @ (AT)

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
  resolution: '720p',
  duration: 10,
  aspect_ratio: '16:9',
  sound: true,
  images: [
    'https://example.com/explorer-reference.jpg',
    'https://example.com/environment-reference.png'
  ],
  videos: ['https://example.com/camera-movement-reference.mp4'],
  audios: ['https://example.com/voice-reference.mp3']
}
```

## ข้อจำกัดสื่อ

ข้อจำกัดเหล่านี้ใช้กับภาพเฟรมแรก ภาพเฟรมสุดท้าย และสื่ออ้างอิงสำหรับโมเดลในหน้านี้

| สื่อ | รูปแบบ | ข้อจำกัด |
|-------|---------|--------|
| ภาพ | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | แต่ละภาพต้องเล็กกว่า 30 MB ความกว้างและความสูงต้องอยู่ที่ 300-6000 px ทั้งสองด้าน อัตราส่วนความกว้างต่อความสูงต้องเป็น 0.4-2.5 |
| วิดีโอ | MP4, MOV | ไม่เกิน 200 MB ต่อรายการ ความกว้างและความสูงต้องอยู่ที่ 300-6000 px ทั้งสองด้าน อัตราส่วนความกว้างต่อความสูงต้องเป็น 0.4-2.5 อัตราเฟรมต้องเป็น 24-60 FPS |
| เสียง | WAV, MP3 | ไม่เกิน 15 MB ต่อรายการ |
| เนื้อหาคำขอ | — | ไม่เกิน 64 MB |

เสียงอ้างอิงและวิดีโออ้างอิงมีขีดจำกัดความยาวรวมแยกกันที่ประเภทละ 30 วินาที จำนวนก็แยกกัน โดยรองรับภาพสูงสุด 30 ภาพ วิดีโอ 10 รายการ และเสียง 10 คลิป การเพิ่มวิดีโอไม่ลดจำนวนภาพที่อนุญาต

ทุกโมเดลใช้ `720p` เป็นค่าเริ่มต้น แต่ยังต้องส่ง `resolution` สวิตช์เสียงมีค่าเริ่มต้นเป็น `true` ทั้งสวิตช์นี้และเสียงอ้างอิงไม่ส่งผลต่อราคา

## รูปแบบการตอบกลับ

### การตอบกลับเริ่มต้น

ทุกโมเดลส่งคืน `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/{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`: สร้างวิดีโอไม่สำเร็จ

## เวลาประมวลผล

เวลาประมวลผลขึ้นอยู่กับความยาว ความละเอียด และสภาพคิวปัจจุบัน

ตรวจสอบสถานะทุก 5-10 วินาที

## แนวทางปฏิบัติที่แนะนำ

1. **พารามิเตอร์ที่จำเป็น**: ส่ง `resolution` และ `duration` เสมอ และส่ง `aspect_ratio` สำหรับข้อความเป็นวิดีโอและสื่ออ้างอิงเป็นวิดีโอ
2. **อัตราส่วนภาพเป็นวิดีโอ**: อย่าส่ง `aspect_ratio` ในคำขอภาพเป็นวิดีโอ
3. **วิดีโออ้างอิง**: วิดีโอไม่บังคับ ความยาวแต่ละวิดีโอและความยาวรวมต้องอยู่ในข้อจำกัดที่ระบุ
4. **ภาพอ้างอิง**: ภาพไม่บังคับและเป็นอิสระจากวิดีโอและเสียง ส่ง URL ภาพที่รองรับได้สูงสุด 30 รายการ
5. **เสียงอ้างอิง**: แต่ละคลิปต้องยาว 2-30 วินาทีและไม่เกิน 15 MB โดยความยาวรวมไม่เกิน 30 วินาที
6. **ลำดับสื่ออ้างอิง**: เรียง `images`, `videos` และ `audios` ตามที่ต้องการ และอ้างถึงให้สอดคล้องกันในพรอมต์
7. **เสียง**: ละ `sound` เพื่อใช้ค่าเริ่มต้น `true` หรือกำหนดเป็น `false` เพื่อปิดการสร้างเสียง