# 通义万相 Wan 与 HappyHorse 视频 API：时长、分辨率、画幅与报错

Source: https://ofox.io/zh/docs/develop/models/wan

阿里巴巴的视频生成模型，共六款，通过 OfoxAI 视频接口 `POST /v1/videos` 调用。任务以异步方式执行：创建任务后获得任务 ID，再通过该 ID 查询结果。

## 模型选择

**要点**:需要 30 秒时长、480p 或 4:3 画幅时选用 Wan 3.0；需要 2 至 3 秒的短视频时，仅阿里系模型支持。

| 模型 | 分辨率（默认） | 时长 | 画幅 | 视频参考 |
|---|---|---|---|---|
| Wan 3.0 Prime | `480p` `720p` `1080p`（`1080p`） | 2–30 秒 | `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` | 支持 |
| Wan 3.0 | `480p` `720p` `1080p`（`1080p`） | 2–30 秒 | 同上 | 支持 |
| Wan 2.7 | `720p` `1080p`（`1080p`） | 2–15 秒 | `16:9` `9:16` `1:1` | 支持 |
| Wan 2.6 | `720p` `1080p`（`1080p`） | 2–15 秒 | `16:9` `9:16` `1:1` | 不支持 |
| HappyHorse 1.0 | `720p` `1080p`（`1080p`） | 3–15 秒 | `16:9` `9:16` `1:1` | 支持 |
| HappyHorse 1.1 | `720p` `1080p`（`1080p`） | 3–15 秒 | `16:9` `9:16` `1:1` | 不支持 |

六款均支持文生视频与图生视频，并可生成同步音轨（`generate_audio` 默认为 `true`）。`adaptive` 表示沿用输入图片的比例。

**模型 ID（调用时原样复制）**

- Wan 3.0 Prime: `alibaba/wan-3.0-prime` — 30 秒、480p 至 1080p
- Wan 3.0: `alibaba/wan-3.0` — 30 秒、480p 至 1080p
- Wan 2.7: `alibaba/wan-2.7` — 2 至 15 秒
- Wan 2.6: `alibaba/wan-2.6` — 不支持视频参考
- HappyHorse 1.0: `alibaba/happyhorse-1.0` — 3 至 15 秒
- HappyHorse 1.1: `alibaba/happyhorse-1.1` — 不支持视频参考

上表与 [Models API](https://ofox.io/zh/docs/api/openai/models) 返回的 `video_attributes` 一致；模型能力如有调整，以接口返回为准。按秒计费，实际费用以任务结果中的 `usage.video_cost` 为准，价格请参阅[模型页](https://ofox.io/zh/models/alibaba/wan-3.0)。

**请显式传入 `resolution`。** 这六款未传入时均默认为 `1080p`，费用按分辨率档位计算。用于预览或社交媒体竖版视频时，建议使用 `720p` 或 `480p`。

## 调用示例
以下示例只展示创建任务的请求。创建后查询状态、下载结果的完整流程见 [Video API · 快速开始](https://ofox.io/zh/docs/api/videos#quickstart)。

**文生视频**

仅传 `prompt`。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-3.0",
    "prompt": "清晨的江南水乡，小船缓缓划过石桥",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

**图生视频**

`frame_images` 传入 1 张 `first_frame`，视频以该图片作为首帧。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-3.0",
    "prompt": "画面中的人物转身走向远处",
    "duration": 5,
    "resolution": "720p",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "frame_type": "first_frame" }
    ]
  }'
```

**视频参考**

`input_references` 传入 1 段视频作为参考。Wan 2.6 与 HappyHorse 1.1 不支持视频参考。以视频为输入时，计费秒数可能包含输入视频的时长。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-2.7",
    "prompt": "保持镜头运动，将画面改为水墨动画风格",
    "duration": 5,
    "resolution": "720p",
    "input_references": [
      { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" } }
    ]
  }'
```

- `frame_images` 与 `input_references` 不可同时传入，同时传入返回 `400 references_conflict`。
- 不需要音轨时传入 `"generate_audio": false`。
- 字段结构的完整说明见[创建视频任务](https://ofox.io/zh/docs/api/videos/create)。

## 与其他系列的差异

**要点**:任务提交后无法取消；视频地址为临时地址，请及时下载。

- **无法取消**：任务提交至上游后，`DELETE /v1/videos/{id}` 返回 `400 cancel_not_supported`，任务将继续生成并计费。提交前请确认参数。
- **视频地址**：实测任务完成后仅返回 `unsigned_urls`（阿里云 OSS 临时地址），不含 `mirror_urls`。临时地址可能在 24 小时后失效，请及时下载保存。
- **更短的时长**：Wan 最短 2 秒，HappyHorse 最短 3 秒，其他系列最短为 4 秒。

## 去水印
阿里系模型的专有参数通过 `provider.options.dashscope` 传递：

```json
{
  "model": "alibaba/wan-3.0",
  "prompt": "...",
  "duration": 5,
  "resolution": "720p",
  "provider": {
    "options": { "dashscope": { "watermark": false } }
  }
}
```

`provider.options` 仅传递给匹配的供应商，其他供应商不会收到。完整说明见[视频供应商路由](https://ofox.io/zh/docs/api/videos/provider-routing)。

## 常见报错

**要点**:参数校验错误在创建时即返回，不会创建任务，也不产生费用。报错信息中会列出允许的取值。

| HTTP · code | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `unsupported_parameter` | `duration 31 out of range [2, 30]` | 时长超出该模型范围 | Wan 3.0 为 2–30 秒，Wan 2.x 为 2–15 秒，HappyHorse 为 3–15 秒 |
| 400 `unsupported_parameter` | `aspect_ratio "4:3" not supported; allowed: [16:9 9:16 1:1]` | Wan 2.x 与 HappyHorse 不支持 4:3、3:4 | 改用 Wan 3.0，或改用支持的比例 |
| 400 `unsupported_parameter` | `mixref2video requests are not supported by this model` | Wan 2.6、HappyHorse 1.1 不支持视频参考 | 移除 `video_url` 参考，或改用 Wan 2.7、Wan 3.0、HappyHorse 1.0 |
| 400 `cancel_not_supported` | `provider does not support task cancellation` | 阿里系任务提交后不支持取消 | 任务将继续执行至完成 |
| 400 `references_conflict` | `frame_images and input_references are mutually exclusive` | 同时传入了两种素材字段 | 两者只能选择其一 |
| 404 `model_not_found` | `model not found` | 模型 ID 拼写错误 | 从本页复制模型 ID |

完整错误码见 [Video API 错误码](https://ofox.io/zh/docs/api/videos/errors)。

## 官方文档
- [阿里云百炼 · 模型服务文档](https://help.aliyun.com/zh/model-studio/)
- [OfoxAI · 创建视频任务](https://ofox.io/zh/docs/api/videos/create)

## 常见问题

**Wan 视频最长能生成多少秒？**

Wan 3.0 和 Wan 3.0 Prime 单个任务 2 至 30 秒；Wan 2.6、Wan 2.7 为 2 至 15 秒；HappyHorse 1.0、1.1 为 3 至 15 秒。超出范围返回 400 duration out of range。

**Wan 视频怎么去掉水印？**

在请求中加入 provider.options.dashscope.watermark: false。provider.options 只会传给阿里云百炼（dashscope）这个供应商。

**Wan 视频任务可以取消吗？**

不可以。阿里系模型的任务提交到上游后无法中断，DELETE 会返回 400 cancel_not_supported，任务会继续生成并计费。提交前请确认参数。

**Wan 2.6 报错 mixref2video requests are not supported by this model？**

Wan 2.6 和 HappyHorse 1.1 不支持用视频作为参考。删除 input_references 中的 video_url，或改用 Wan 2.7、Wan 3.0、HappyHorse 1.0。

**Wan 支持 4:3 或 3:4 吗？**

只有 Wan 3.0 和 Wan 3.0 Prime 支持 4:3、3:4 和 adaptive。Wan 2.x 和 HappyHorse 只支持 16:9、9:16、1:1。

**Wan 生成的视频地址多久失效？**

完成后返回的是 unsigned_urls，即阿里云 OSS 的临时地址，可能 24 小时后失效，请及时下载保存。