# Seedance 2.5 API

字节跳动 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` 可禁用声音生成