# wan 3.0 视频生成 API 对接文档

## 概述

wan 3.0 是新一代全能视频生成接口，支持文本、首尾帧图片、多图参考、参考视频等多模态输入生成视频，在画面质量、镜头稳定性和多模态理解上较上一代显著提升，并支持可选音频生成。

**特性**：
- 🎬 **旗舰画质**：新一代模型，画面细节、动态表现与镜头稳定性全面升级
- 🧠 **全能多模态**：支持文生、图生（首帧/尾帧）、多图参考、视频参考/续写
- 🔊 **可选音频**：支持在生成视频的同时输出音频
- 🎞️ **更长时长**：单次生成最长支持 30 秒
- ⚡ **双版本**：标准版与高速版可选，兼顾画质与出图速度
- 🇨🇳 **国内专线**：专为国内用户优化的访问速度

**限制**：
- ⚠️ **分辨率限制**：支持 480P / 720P / 1080P，不支持 4K

**Base URL**: `https://api.apiverse.ai`（国内专线）

---

## 认证方式

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

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

---

## 支持的使用场景

### 场景1：文生视频（t2v）

纯文本描述生成视频。

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

### 场景2：首帧图片生视频（i2v）

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

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/wan3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，镜头缓缓拉出，女孩的头发被风吹动",
    "modelName": "wan3.0-video",
    "firstFrameImage": "https://example.com/fox_girl.png",
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720P"
  }'
```

### 场景3：首尾帧生视频（se2v）

同时传入首帧与尾帧图片，模型生成从首帧过渡到尾帧的视频。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/wan3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "花朵从含苞待放到完全绽放的过程，镜头缓缓推进",
    "modelName": "wan3.0-video",
    "firstFrameImage": "https://example.com/bud.png",
    "lastFrameImage": "https://example.com/bloom.png",
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720P"
  }'
```

### 场景4：多图参考生视频（mi2v）

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

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

### 场景5：视频参考/续写（v2v）

传入参考视频进行续写或重绘，可同时附带参考图（`referenceImages`）辅助控制画面。传入参考视频时，输出视频比例与时长将自动跟随输入视频（强制智能时长）。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/wan3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "延续视频中人物的动作，镜头缓缓拉远展现全景",
    "modelName": "wan3.0-video",
    "videoUrl": "https://example.com/source_video.mp4",
    "referenceImages": [
      "https://example.com/style_ref.png"
    ],
    "resolution": "720P"
  }'
```

> v2v 可同时传参考视频（`videoUrl`）与参考图（`referenceImages`，最多10张），二者可并存，不必只传视频。

---

## 查询任务状态

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

---

## 接口详情

### 1. 创建 wan 3.0 任务

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

创建一个 wan 3.0 视频生成任务。

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 视频描述提示词 |
| modelName | string | 否 | 版本：`wan3.0-video`(标准，默认) / `wan3.0-video-prime`(高速) |
| genType | string | 否 | 生成类型：`t2v` / `i2v` / `se2v` / `mi2v` / `v2v`。不传时由系统按输入素材自动推断 |
| firstFrameImage | string | 否 | 首帧图片 URL（i2v / se2v） |
| lastFrameImage | string | 否 | 尾帧图片 URL（se2v） |
| referenceImages | string[] | 否 | 参考图片 URL 列表（mi2v 场景引用；v2v 场景可与 `videoUrl` 并存，最多10张） |
| videoUrl | string | 否 | 参考/续写视频 URL（v2v）。可与 `referenceImages` 并存 |
| imageUrls | string[] | 否 | 通用图片素材 URL 列表（按 genType 语义组装，可替代上述图片字段） |
| ratio | string | 否 | 宽高比：`adaptive`(默认) / `16:9` / `9:16` / `1:1` / `4:3` / `3:4`。传入参考视频时强制 `adaptive` |
| duration | int | 否 | 视频时长（秒）。取值 `-1`（智能时长，模型自行决定输出时长）或 `2~30` 的整数，默认 5。传入参考视频（v2v）时强制智能时长，自动跟随输入视频 |
| resolution | string | 否 | 输出分辨率：`480P` / `720P`(默认) / `1080P` |
| audio | bool | 否 | 是否生成音频，默认 `false` |
| watermark | bool | 否 | 是否带水印，默认 `false` |
| seed | int | 否 | 随机种子，用于复现结果 |
| nsfwChecker | bool | 否 | 内容过滤开关 |
| promptExtend | bool | 否 | 提示词智能改写开关。开启后由模型对提示词进行智能扩写/改写以提升生成效果；不传则使用默认策略 |
| taskNickname | string | 否 | 任务昵称，便于在控制台识别 |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

> **说明**：
> - 在提示词中通过 "图片1"、"图片2" 引用 `referenceImages` 中对应位置的参考素材
> - 参考图片最多10张
> - 传入参考视频（`videoUrl`）时，输出视频的比例与时长将自动跟随输入视频（等效于 `ratio=adaptive`，且强制智能时长），此时指定的 `ratio` / `duration` 不生效
> - v2v 场景可同时传参考视频（`videoUrl`）与参考图（`referenceImages`），二者并存，不必只传视频
> - `duration` 传 `-1` 时启用智能时长，由模型自行决定输出视频时长
> - **支持 480P / 720P / 1080P 分辨率**

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| 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.output | object | 生成结果与用量（成功时返回） |
| data.output.video_url | string | 生成视频 URL |
| data.output.usage | object | 用量对象，用于核对计费，详见「计费说明」 |
| data.errorMsg | string | 错误信息（失败时返回） |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 更新时间 |

#### 响应示例

**处理中**
```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-cn-shanghai.aliyuncs.com/videos/2026/05/08/output.mp4"
    ],
    "output": {
      "video_url": "https://fc-gw-sh.oss-cn-shanghai.aliyuncs.com/videos/2026/05/08/output.mp4",
      "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "billing_duration": 5,
        "fps": 24,
        "SR": 1,
        "ratio": "16:9"
      }
    },
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:03:30"
  }
}
```

**失败**
```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-cn-shanghai.aliyuncs.com/videos/output.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-08T15:03:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

---

## 参数取值范围

### 版本 (modelName)

| 值 | 说明 |
|----|------|
| `wan3.0-video` | 标准版（默认），画质优先 |
| `wan3.0-video-prime` | 高速版，出图速度更快 |

### 生成类型 (genType)

| 值 | 说明 | 所需素材 |
|----|------|----------|
| `t2v` | 文生视频 | 无 |
| `i2v` | 首帧图生视频 | firstFrameImage |
| `se2v` | 首尾帧生视频 | firstFrameImage + lastFrameImage |
| `mi2v` | 多图参考生视频 | referenceImages（最多10张） |
| `v2v` | 视频参考/续写 | videoUrl（参考视频）+ referenceImages（参考图，可选，最多10张） |

> 不传 `genType` 时，系统按输入素材自动推断。

### 分辨率 (resolution)

| 值 | 说明 |
|----|------|
| `480P` | 低清 |
| `720P` | 默认，推荐 |
| `1080P` | 高清 |

> **注意**：wan 3.0 不支持 4K

### 宽高比 (ratio)

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

### 时长 (duration)

- 取值：`-1`（智能时长，由模型自行决定输出时长）或 `2 ~ 30` 秒的整数
- 默认：5 秒
- 视频参考/续写场景（输入含 `videoUrl`）强制智能时长，自动跟随输入视频

---

## 计费说明

### 计费方式

- 视频生成**按时长计费**（by second）：按**输出分辨率档位**（480P / 720P / 1080P）确定每秒单价，分辨率越高每秒单价越高。
- 计费金额 = 每秒单价 × 计费时长。

### 计费时长 = 输入视频时长 + 输出视频时长

计费时长并非只看输出视频时长，而是：

```
计费时长 = input_video_duration + output_video_duration
```

- 文生视频（t2v）、首帧图生视频（i2v）、首尾帧（se2v）、多图参考（mi2v）等**无输入视频**的场景，输入视频时长为 0，即按输出视频时长计费。
- **视频参考/续写（v2v，带 `videoUrl` 输入）** 场景，参考视频本身的时长也会**计入计费时长**。即实际计费时长 = 参考视频时长 + 生成视频时长，会高于仅按输出时长估算的结果，请在预估成本时留意。

### 用量核对

任务查询成功后，`data.output` 下会返回 `usage` 用量对象，可据此核对计费：

| 字段 | 类型 | 说明 |
|-----|------|------|
| duration | number | 生成视频总时长（秒） |
| input_video_duration | number | 输入视频时长（秒），无视频输入时为 0 |
| output_video_duration | number | 输出视频时长（秒） |
| billing_duration | int | 计费时长（秒）= input_video_duration + output_video_duration |
| fps | number | 帧率 |
| SR | number | 超分倍数 |
| ratio | string | 实际宽高比 |

**v2v 场景 usage 示例**（参考视频 3 秒 + 输出 5 秒，计费按 8 秒）：

```json
{
  "usage": {
    "duration": 5,
    "input_video_duration": 3,
    "output_video_duration": 5,
    "billing_duration": 8,
    "fps": 24,
    "SR": 1,
    "ratio": "16:9"
  }
}
```

---

## 错误码

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

---

## 最佳实践

### 1. 轮询策略

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

### 2. 处理时间参考

- 纯文本生视频：通常 1 ~ 3 分钟
- 图片+文本生视频：通常 1 ~ 3 分钟
- 视频参考/续写：通常 2 ~ 4 分钟
- 时长越长，处理时间越长

### 3. Prompt 建议

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

---

## 常见问题

### Q1: 标准版和高速版怎么选？

**A**: 标准版（`wan3.0-video`）画质优先，适合追求高质量画面的场景；高速版（`wan3.0-video-prime`）出图速度更快，适合对时效敏感的场景。

### Q2: 单次最长能生成多长的视频？

**A**: `2 ~ 30` 秒，或传 `duration=-1` 启用智能时长（由模型自行决定输出时长）。视频参考/续写场景（输入含 `videoUrl`）下强制智能时长，输出时长自动跟随输入视频。

### Q3: 参考图片最多传几张？

**A**: 多图参考（mi2v）最多传 10 张，在提示词中通过 "图片1"、"图片2" 引用。

---

## 技术支持

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