# Seedance 2.0 Mini API

字节跳动 Seedance 2.0 Mini 视频生成模型的完整 API 参考。

## 模型变体

此 API 支持三种模型变体：

| 模型 | ID | 说明 |
|-------|-----|-------------|
| **Seedance 2.0 Mini Text to Video** | `seedance-v2.0-mini-text-to-video` | 高性价比文生视频 |
| **Seedance 2.0 Mini Image to Video** | `seedance-v2.0-mini-image-to-video` | 支持运动控制的高性价比图生视频 |
| **Seedance 2.0 Mini Reference to Video** | `seedance-v2.0-mini-reference-to-video` | 由参考图片、视频及音频引导的高性价比视频生成 |

## 快速对比

| 功能 | 值 |
|---------|-------|
| 时长范围 | 4-15 秒 |
| 分辨率选项 | 480p, 720p |
| 宽高比选项 | 21:9, 16:9, 9:16, 1:1, 4:3, 3:4 |
| 音频支持 | 支持（默认开启） |
| 参考素材 | 参考生视频支持图片、视频和音频 |
| 种子控制 | 所有 Seedance 2.0 Mini 模型均不支持 |

### 支持的宽高比

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

### 分辨率选项

| 分辨率 | 说明 |
|------------|-------------|
| `480p` | 标清，处理速度更快 |
| `720p` | 高清 |

## Seedance 2.0 Mini Text to Video

### 接口端点

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

### 请求参数

#### 必填

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `model_name` | string | 必须为 `"seedance-v2.0-mini-text-to-video"` |
| `prompt` | string | 视频生成提示词 |
| `duration` | integer | 视频时长，整数秒（4-15），步长为 1 |
| `resolution` | string | 输出分辨率：`"480p"` 或 `"720p"` |
| `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.0-mini-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Image to Video

### 请求参数

#### 必填

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `model_name` | string | 必须为 `"seedance-v2.0-mini-image-to-video"` |
| `prompt` | string | 视频生成提示词 |
| `duration` | integer | 视频时长，整数秒（4-15），步长为 1 |
| `resolution` | string | 输出分辨率：`"480p"` 或 `"720p"` |
| `aspect_ratio` | string | 视频宽高比：`"21:9"`、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"` 或 `"3:4"` |
| `image_url` | string | 视频首帧 |

#### 选填

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `image_end_url` | string | 可选的尾帧图片 URL |
| `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.0-mini-image-to-video',
    image_url: 'https://example.com/image.jpg',
    image_end_url: 'https://example.com/end-frame.jpg',
    prompt: 'Camera slowly pulls back to reveal the full landscape',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Reference to Video

### 请求参数

#### 必填

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `model_name` | string | 必须为 `"seedance-v2.0-mini-reference-to-video"` |
| `prompt` | string | 视频生成提示词。可以编写不含占位符的普通提示词，也可以使用 @ (AT) 引用功能，通过 `<<<image_N>>>`、`<<<video_N>>>` 和 `<<<audio_N>>>` 显式引用对应素材数组中的元素 |
| `duration` | integer | 视频时长，整数秒（4-15），步长为 1 |
| `resolution` | string | 输出分辨率：`"480p"` 或 `"720p"` |
| `aspect_ratio` | string | 视频宽高比：`"21:9"`、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"` 或 `"3:4"` |

#### 参考素材

每个请求必须至少包含一张图片或一段视频。使用图片参考时提交 1-9 张图片。仅当 `videos` 数组包含至少一段参考视频时，才可省略 `images` 数组或将其设为空。不支持仅音频的请求。

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `images` | string[] | 1-9 个参考图片 URL；`videos` 非空时可为空数组 |
| `videos` | string[] | 最多 3 个参考视频 URL；单段视频 2-15 秒，总时长不超过 15 秒 |
| `audios` | string[] | 最多 3 个参考音频 URL；单段音频 2-15 秒，总时长不超过 15 秒；WAV 或 MP3，单段不超过 15 MB；至少需要一张图片或一段视频 |

#### @ (AT) 引用占位符

@ (AT) 引用功能通过带编号的 `<<<...>>>` 占位符将参考素材关联到提示词。每种素材类型独立从 `1` 开始编号，顺序与对应数组一致：

| 占位符 | 引用值 |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

每个占位符必须指向对应数组中存在的元素。

#### 选填

| 参数 | 类型 | 说明 |
|-----------|------|-------------|
| `sound` | boolean | 是否生成同步声音。默认为 `true` |

### 参考视频计费

Seedance V2.0 Mini Reference-to-Video 与其他 Seedance 2.0 参考生视频变体采用相同的按分辨率、按秒计费结构。当 `videos` 数组包含至少一段参考视频时，生成总费用乘以 2。该倍数仅应用一次，与上传参考视频的数量或时长无关。

### 请求示例

```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.0-mini-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>>>',
    duration: 8,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true,
    images: [
      'https://example.com/explorer-reference.jpg',
      'https://example.com/environment-reference.jpg'
    ],
    videos: ['https://example.com/camera-movement-reference.mp4'],
    audios: ['https://example.com/voice-reference.mp3']
  })
});

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

## 素材限制

这些限制适用于本页模型的首帧图片、尾帧图片和参考素材。

| 素材 | 格式 | 限制 |
|-------|---------|--------|
| 图片 | 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 |

参考音频与参考视频各自的总时长上限均为 15 秒，独立计算。数量上限也相互独立：最多 9 张图片、3 段视频和 3 段音频。添加视频不会减少允许上传的图片数量。

所有模型默认使用 `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`：视频生成失败

## 处理时间

通常处理时间为 2-6 分钟，取决于时长和分辨率。

每 5-10 秒轮询一次以检查状态。

## 最佳实践

1. **清晰描述运动**：在提示词中加入具体的运动描述
2. **分辨率选择**：使用 `480p` 加快处理，使用 `720p` 获得更高画质
3. **音频增强**：保持 `sound` 开启，获得更具沉浸感的视频体验
4. **图生视频**：通过 `image_url` 提供清晰的首帧；需要控制首尾帧时使用 `image_end_url`
5. **参考素材**：使用支持的图片、视频和音频参考，并确保至少包含一张图片或一段视频
6. **参考视频计费**：任何包含至少一段参考视频的参考生视频请求均按 2 倍计费，与上传视频的数量或时长无关
7. **种子参数**：不要发送 `seed`；Seedance 2.0 Mini 模型不支持此参数