# Seedance 2.5 API

ByteDance Seedance 2.5 影片生成模型的完整 API 參考。

## 模型版本

此 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` | 全高畫質 |

## Seedance 2.5 Text to Video

### 端點

```
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[] | 0-30 個參考圖片 URL；請參閱下方素材限制 |
| `videos` | string[] | 0-10 個 MP4 或 MOV 格式的參考影片 URL；每段影片須為 2-30 秒，總時長不得超過 30 秒 |
| `audios` | string[] | 0-10 個 WAV 或 MP3 格式的參考音訊 URL；每段音訊須為 2-30 秒且不超過 15 MB，總時長不得超過 30 秒 |

#### @ (AT) 參照預留位置

@ (AT) 參照功能透過帶有編號的 `<<<...>>>` 預留位置，將參考素材與提示詞連結。每種素材類型各自從 `1` 開始編號，並依照對應陣列的順序：

| 預留位置 | 參照值 |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

例如，若第一張圖片是角色參考，第二張是場景參考，請在 `prompt` 中使用 `<<<image_1>>>` 指定角色，並使用 `<<<image_2>>>` 指定場景。每個預留位置都必須指向對應陣列中實際存在的項目。

#### 選填

| 參數 | 類型 | 說明 |
|-----------|------|-------------|
| `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. **參考圖片**：圖片獨立於影片和音訊，為選填項目；最多提交 30 個支援格式的圖片 URL
5. **參考音訊**：每段音訊維持在 2-30 秒且不超過 15 MB，總時長不得超過 30 秒
6. **參考素材順序**：依照預期順序排列 `images`、`videos` 和 `audios`，並在提示詞中一致地參照
7. **聲音**：省略 `sound` 即使用預設值 `true`，設為 `false` 則停用聲音生成