# Seedance 2.0 Mini Oversea 视频生成 API 对接文档

## 概述

Seedance 2.0 Mini Oversea 是经济型视频生成接口，支持文本、图片、视频、音频等多模态输入生成视频。

**特性**：
- ⚡ **更快速度**：生成速度优于标准版本
- 💰 **更低成本**：计费单价显著低于标准版本，适合大批量、成本敏感的场景
- 🌍 **海外加速**：专为海外用户优化的访问速度
- 🎯 **适用场景**：适合对成本和速度敏感、对极致画质要求不高的场景

**限制**：
- ⚠️ **分辨率限制**：仅支持 480p 和 720p，不支持 1080p

**Base URL**: `https://api.apiverse.ai`（海外加速）

---

## 认证方式

所有接口均需要在请求头中携带 Token 进行认证：

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

---

## 支持的使用场景

### 场景1：文生视频

纯文本描述生成视频，结果具有较大随机性。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近，最终定格在一朵雏菊花的特写上，花瓣上有几颗晶莹的露珠"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generateAudio": true
  }'
```

### 场景2：首帧/尾帧图片生视频

传入首帧或尾帧图片，模型基于图片内容生成视频。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出，女孩的头发被风吹动"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/fox_girl.png"
        },
        "role": "first_frame"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'
```

### 场景3：多图参考生视频

传入多张参考图片，在提示词中通过 "图片1"、"图片2" 引用（最多9张）。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "[图片1]戴着眼镜穿着蓝色T恤的男生和[图片2]的柯基小狗，坐在[图片3]的草坪上，视频卡通风格"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/boy.png" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/dog.png" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/grass.png" },
        "role": "reference_image"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'
```

### 场景4：多模态参考生成（图片+视频+音频）

同时参考图片、视频和音频素材进行视频生成。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "以图片1为首帧，全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/pic1.jpg"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/video1.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/audio1.mp3"
        },
        "role": "reference_audio"
      }
    ],
    "ratio": "16:9",
    "duration": 11,
    "resolution": "720p",
    "generateAudio": true
  }'
```

### 场景5：编辑视频

替换视频中的主体、局部画面重绘/修复等。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "将视频1中的房子外立面墙壁刷成蓝色，天气改为雪天"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/house_video.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/snow_scene.jpg"
        },
        "role": "reference_image"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'
```

---

## 查询任务状态

```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/{taskId}" \
  -H "Authorization: Bearer your_auth_token_here"
```

---

## 接口详情

### 1. 创建 Seedance2 Mini Oversea 任务

**POST** `/api/v2/open/aigc/seedance2-0-mini-oversea`

创建一个 Seedance 2.0 Mini Oversea 视频生成任务。

**Content-Type**: `application/json`

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| content | array | 是 | 内容数组，详见下方 [content 内容项](#content-内容项) |
| ratio | string | 否 | 宽高比：`16:9`(默认) / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive` |
| duration | int | 否 | 视频时长（秒），范围 4~15，默认 5 |
| resolution | string | 否 | 输出分辨率：`480p` / `720p`(默认)。**Mini 版本不支持 1080p** |
| generateAudio | bool | 否 | 是否生成音频，默认 `true` |
| watermark | bool | 否 | 是否带水印，默认 `false` |
| seed | int | 否 | 随机种子，用于复现结果 |
| cameraFixed | bool | 否 | 是否固定摄像头 |
| returnLastFrame | bool | 否 | 是否返回视频尾帧图片URL（已弃用） |
| webSearch | bool | 否 | 是否启用在线搜索 |
| nsfwChecker | bool | 否 | 内容过滤开关，默认 `false` |
| realPersonMode | bool | 否 | 真人模式开关，默认 `true` |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

#### content 内容项

content 为数组，每个元素为一个内容项：

| 类型 | 字段 | 说明 |
|-----|------|------|
| text | `type`: "text", `text`: "提示词" | **必须**，视频描述提示词（3-20000字符） |
| image_url | `type`: "image_url", `image_url`: {"url": "URL"}, `role`: 见下方 | 参考图片（最多9张，支持jpeg/png/webp/bmp/tiff/gif，宽高比0.4-2.5，尺寸300-6000px，最大30MB） |
| video_url | `type`: "video_url", `video_url`: {"url": "URL"}, `role`: "reference_video" | 参考视频（最多3个，mp4/mov，480p/720p，2-15秒，最大50MB，24-60FPS） |
| audio_url | `type`: "audio_url", `audio_url`: {"url": "URL"}, `role`: "reference_audio" | 参考音频（最多3个，wav/mp3，2-15秒，最大15MB） |

#### image_url 的 role 取值

| role 值 | 说明 |
|---------|------|
| `reference_image` | 参考图片 |
| `first_frame` | 首帧图片 |
| `last_frame` | 尾帧图片 |

> **说明**：
> - content 数组中**必须包含至少一个 text 类型**的内容项作为提示词
> - 在提示词中通过 "图片1"、"图片2"、"视频1"、"音频1" 引用对应位置的参考素材
> - 参考图片最多9张，参考视频最多3个（总时长不超过15秒），参考音频最多3个（总时长不超过15秒）
> - 输入包含视频时，计费价格与纯文本/图片输入不同
> - **Mini 版本仅支持 480p 和 720p 分辨率，不支持 1080p**
> - `generateAudio` 默认为 `true`（海外版本特性）
> - `realPersonMode` 默认为 `true`，开启真人模式优化

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID，用于查询任务状态 |
| data.status | string | 任务状态，创建时固定为 `processing` |
| data.createdAt | string | 创建时间 |

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 15:00:00"
  }
}
```

---

### 2. 查询任务状态

**GET** `/api/v2/open/aigc/{taskId}`

查询单个任务的执行状态。

#### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskId | string | 是 | 任务 ID |

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID |
| data.status | string | 任务状态：`processing` / `success` / `failed` |
| data.result | string[] | 生成的视频 URL 列表（成功时返回） |
| data.errorMsg | string | 错误信息（失败时返回） |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 更新时间 |
| data.completionTokens | int | 实际 token 用量（仅按 token 计费的任务在结算完成后返回；按秒计费或尚未结算时不返回该字段） |

#### 响应示例

**处理中**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:00:05"
  }
}
```

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/08/output.mp4"
    ],
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:03:30",
    "completionTokens": 108000
  }
}
```

> **说明**：`completionTokens` 为上游返回的实际 token 用量，仅在【按 token 计费】的任务结算完成后返回。按秒计费的任务、以及尚未结算完成的任务不会返回该字段。

**失败**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "failed",
    "errorMsg": "视频生成失败，请重试",
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:02:00"
  }
}
```

---

### 3. 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

批量查询多个任务的执行状态（最多 100 个）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskIds | string[] | 是 | 任务 ID 列表，最多 100 个 |

#### 请求示例

```json
{
  "taskIds": ["task_20260508150000_abc12345", "task_20260508150200_def67890"]
}
```

---

## 回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。

### 回调请求

**Headers**
```
Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}
```

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260508150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-08T15:03:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

---

## 海外三个版本对比

Seedance 2.0 海外系列共有三个版本，接口协议、content 结构、使用场景完全一致，仅在画质档位、速度、价格和分辨率支持上不同。三者请求/响应格式相同，可无缝切换，只需更换接口路径。

| 项目 | 标准 Oversea | Fast Oversea | Mini Oversea |
|------|-------------|--------------|--------------|
| 接口路径 | `/aigc/seedance2-0-oversea` | `/aigc/seedance2-0-fast-oversea` | `/aigc/seedance2-0-mini-oversea` |
| 定位 | 旗舰画质 | 速度与成本均衡 | 极致经济型 |
| 生成速度 | 标准 | 更快 | 最快 |
| 计费单价 | 标准（最高） | 低于标准版 | 最低 |
| 分辨率支持 | 480p / 720p / 1080p | 480p / 720p | 480p / 720p |
| 1080p 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不支持 |
| 画质表现 | 最高质量 | 良好 | 经济型 |
| generateAudio 默认值 | true | true | true |
| webSearch 参数 | ✅ | ✅ | ✅ |
| nsfwChecker 参数 | ✅ | ✅ | ✅ |
| watermark 参数 | ✅ | ❌ 不支持 | ✅ |
| cameraFixed 参数 | ✅ | ❌ 不支持 | ✅ |
| realPersonMode 参数 | ✅ | — | ✅（默认开启） |
| 适用场景 | 追求极致画质、需要 1080p | 兼顾质量与成本 | 大批量、成本敏感、快速迭代 |

**如何选择**：
- **标准 Oversea**：最终交付、高质量展示，或需要 1080p 高清输出
- **Fast Oversea**：需要在质量和成本之间取得平衡，可接受 720p 上限
- **Mini Oversea**：预算优先、批量生成、快速预览等场景，以最低单价完成生成

---

## 参数取值范围

### 分辨率 (resolution)

| 值 | 说明 |
|----|------|
| `480p` | 低清 |
| `720p` | 默认，推荐 |

> **注意**：Mini 版本不支持 1080p

### 宽高比 (ratio)

| 值 | 说明 |
|----|------|
| `16:9` | 横屏（默认） |
| `9:16` | 竖屏 |
| `1:1` | 方形 |
| `4:3` | 标准横屏 |
| `3:4` | 标准竖屏 |
| `21:9` | 超宽屏 |
| `adaptive` | 自适应（根据输入图片比例） |

### 时长 (duration)

- 范围：4 ~ 15 秒
- 默认：5 秒

---

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 10006 | 余额不足 |
| 30003 | 任务不存在 |
| 90003 | 服务器内部错误 |

---

## 最佳实践

### 1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

### 2. 处理时间参考

- 纯文本生视频：通常 1 ~ 2 分钟（比标准版更快）
- 图片+文本生视频：通常 1 ~ 2 分钟
- 多模态输入（含视频/音频）：通常 1.5 ~ 3 分钟
- 时长越长，处理时间越长

### 3. Prompt 建议

- 提示词长度：3 ~ 20,000 字符
- 提示词 = 主体 + 运动，背景 + 运动，镜头 + 运动
- 用简洁准确的自然语言写出想要的效果
- 可以指定镜头运动（推进、拉远、环绕等）
- 通过 "图片1"、"图片2"、"视频1"、"音频1" 引用 content 中对应位置的参考素材
- 当生成结果不符合预期时，建议修改提示词，将抽象描述换成具象描述
- 如果有明确的效果预期，建议先用生图模型生成符合预期的图片，再用图生视频

### 4. 版本选择建议

**选择 Mini Oversea 版本**：
- 对成本敏感，希望以更低单价完成生成
- 对生成速度有要求，希望更快获得结果
- 对画质要求不极致，可以接受经济型质量
- 不需要 1080p 分辨率

**选择标准 Oversea 版本**：
- 追求最高画质表现
- 需要 1080p 高清输出
- 对质量要求高于成本考虑

---

## 常见问题

### Q1: Mini 版本与标准版本的主要区别是什么？

**A**: 
- **速度**：Mini 版本生成速度更快
- **价格**：Mini 版本计费单价显著低于标准版
- **分辨率**：Mini 版本仅支持 480p 和 720p，不支持 1080p
- **质量**：Mini 版本为经济型质量，标准版追求极致画质

### Q2: 为什么 Mini 版本不支持 1080p？

**A**: Mini 版本为了提升生成速度和降低成本，在分辨率上做了限制。如果需要 1080p 输出，请使用标准 Oversea 版本（`seedance2-0-oversea`）。

### Q3: Mini 版本的画质表现如何？

**A**: Mini 版本提供经济型画质，适合对速度和成本敏感的场景。在 480p 和 720p 分辨率下，画质能够满足大多数应用需求。如需极致画质表现，建议使用标准版本。

### Q4: 如何获取最佳性价比？

**A**: 
- 对于测试、预览、快速迭代等场景，建议使用 Mini 版本
- 对于最终交付、高质量展示等场景，建议使用标准版本
- 720p 分辨率在 Mini 版本上性价比最高
- 合理使用图片参考可以提升生成效果，同时控制成本

---

## 技术支持

如有疑问，请联系我们的技术支持团队。