# Seedance 2.5 API

ByteDance の Seedance 2.5 動画生成モデルの完全な API リファレンスです。

## モデルの種類

この API は 3 種類のモデルに対応しています。

| モデル | 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` | フル HD |

## 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[] | 参照画像の URL を 0-30 件指定。下記の素材制限を参照 |
| `videos` | string[] | MP4 または MOV 形式の参照動画 URL を 0-10 件指定。各動画は 2-30 秒、合計は最大 30 秒 |
| `audios` | string[] | WAV または MP3 形式の参照音声 URL を 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]` |

例えば、1 枚目がキャラクターの参照画像、2 枚目がシーンの参照画像の場合、`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. **参照画像**：画像は動画や音声とは独立した任意項目です。対応形式の画像 URL を最大 30 件送信できます
5. **参照音声**：各音声は 2-30 秒かつ 15 MB 以下、合計時間は 30 秒以下にしてください
6. **参照素材の順序**：`images`、`videos`、`audios` を意図した順序に並べ、プロンプトでも一貫して参照してください
7. **音声**：`sound` を省略すると既定値 `true` が使用されます。音声生成を無効にするには `false` を指定します