# 万相 3.0 能力总览

> 通义万相 3.0（wan3.0-video / wan3.0-video-prime）全能参考视频生成：模型介绍、技术规格、分辨率与宽高比、最长 30 秒时长、计费方式与常见问题；把 Base URL 指向网关、只换 API Key 即可调用

万相 3.0 是阿里通义万相系列的**全能参考视频生成模型（All-in-One）**，提供 `wan3.0-video` 与 `wan3.0-video-prime` 两个模型，**调用方式完全相同**，用同一个接口统一支持**文生视频**、**图生视频**（首帧 / 首尾帧）与**参考生视频**（参考图 / 参考视频 / 参考音频 / 文件 / 网页链接）。单次最长可生成 **30 秒**视频，输出帧率 **30fps**，并可选择是否携带音轨。LoopRouter 以与阿里百炼（DashScope）**完全一致的原生接口**对外提供该能力：接口路径、请求体、响应结构都与百炼官方相同，**你只需把 Base URL 从百炼域名换成网关地址、把 API Key 换成 LoopRouter 令牌，其余代码一行不改**。

<Note>
**换 Base URL 即可使用**：把原本指向 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 的请求改为 `https://api.looprouter.com` 即可——网关不需要 `WorkspaceId` 子域，也不需要百炼 API Key，统一用 LoopRouter 的 `sk-` 令牌鉴权。已有的百炼官方示例、SDK 或自研代码无需改动请求结构。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/wan3/video-generation">
    完整参数、四种生成模式、media 数组、响应结构与错误码
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频任务
  </Card>
  <Card title="计费与分组" icon="receipt" href="/user-groups">
    分辨率档位单价与分组倍率说明
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    把文档直接交给 ChatGPT / Claude 接入
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="一个接口四种模式" icon="layer-group">
    文生 / 首帧图生 / 首尾帧图生 / 参考生视频，共用同一端点，仅靠 `input.media` 组合区分
  </Card>
  <Card title="全能参考生视频" icon="wand-magic-sparkles">
    参考图 ≤10、参考视频 ≤5、参考音频 ≤5，还可传文件或网页链接，`prompt` 中用「图1」「视频1」指代素材
  </Card>
  <Card title="更长单段时长" icon="clock">
    时长范围 2–30 秒，一次生成覆盖更完整的镜头叙事
  </Card>
  <Card title="音画同步" icon="volume-high">
    `audio` 默认开启，输出视频自带声音；开关声音价格相同
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `wan3.0-video` | 全能参考视频生成标准版，支持全部生成模式，时长最长 30 秒，输出分辨率 480P / 720P / 1080P，帧率 30fps |
| `wan3.0-video-prime` | 全能参考视频生成加强版，调用方式与 `wan3.0-video` 完全一致，接口、请求体、参数、响应结构均相同 |

<Note>
两个模型**调用方式完全相同**，只需切换请求体里的 `model` 字段值即可；实际可用模型与定价以控制台「模型广场」为准，无需关心上游版本后缀或接入点 ID。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 首帧图生 / 首尾帧图生 / 参考生视频 |
| 分辨率 | `480P` / `720P` / `1080P`（默认 `1080P`；传入其他档位返回错误且不扣费） |
| 宽高比 | `adaptive`（默认，跟随输入素材）、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**不支持 `21:9`**） |
| 时长 | **2–30 秒**整数；有视频输入时「输入视频总时长 + 输出时长 ≤ 30 秒」 |
| 帧率 | 固定 30fps |
| 音频 | `audio` 默认 `true`，输出视频含声音；`false` 则无音轨（价格相同） |
| 参考素材 | 参考图 ≤10 张 + 参考视频 ≤5 段（合计 ≤15 秒）+ 参考音频 ≤5 段（合计 ≤15 秒）；或文件 ≤1、网页链接 ≤1 |
| 图片要求 | JPEG/JPG/PNG（不支持透明通道）/BMP/WEBP；单边 [240, 8000]px；长宽比 ≤8:1；小于 20MB |
| 提示词建议 | 支持中英文，≤20000 字符，超出自动截断；台词可用双引号包裹 |
| 任务模式 | 异步任务：`PENDING → RUNNING → SUCCEEDED / FAILED / CANCELED` |
| 成片链接 | `output.video_url` 为临时链接，请在获取后尽快转存 |

<Tip>
`first_frame` / `last_frame`（首帧、尾帧）与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link`（参考类）**互斥**，不能在同一请求中混用。
</Tip>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v1/services/aigc/video-generation/video-synthesis` | 创建视频生成任务 |
| GET | `/api/v1/tasks/{task_id}` | 根据任务 ID 查询结果 |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。`X-DashScope-Async` 头可选，值为 `enabled`。
</Tip>

<Warning>
**与百炼官方的两点取值差异，接入前请留意：**

1. **网关地址不带 `WorkspaceId`**：直接用 `https://api.looprouter.com`，不需要业务空间 ID 子域。
2. **不支持智能时长 `duration: -1`**：请传 2–30 秒的明确整数。提交时长未知会导致按秒计费无法预扣，故网关直接返回参数错误。
</Warning>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程，与 Seedance 2.5 / 可灵 3.0 同一「按秒 × 按分辨率档」机制：

<Steps>
  <Step title="提交预扣">
    任务创建成功后，按请求的分辨率档位与时长预估并预扣一笔额度，日志中心产生一条预扣记录。分辨率越高、时长越长，预扣越多。
  </Step>
  <Step title="完成结算">
    任务成功后按实际输出时长（向上取整到整秒）结算，多退少补；任务失败则全额退回预扣。
  </Step>
</Steps>

按秒计费，单价按分辨率档位区分：分辨率越高单价越高，`1080P`（默认）> `720P` > `480P`。**具体单价以控制台「模型广场」展示为准。**

<Info>
**计费规则**：时长向上取整到整秒，最短按 1 秒、最长按 30 秒计。开关音频（`audio`）不影响价格。

**不扣费场景**：参数校验失败、鉴权失败、内容审核拒绝均不产生费用；已预扣的失败任务会自动退款。
</Info>

实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率（具体折扣以商务对接约定为准），分组同时决定可用的分辨率档位。

## 限流与重试

- 平台按渠道维度做 RPM 智能调度：并发高峰时任务会短暂排队而不是直接失败。
- 收到 429（`Throttling`，当前分组上游负载已饱和）或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔 15 秒；时长越长生成耗时越久，长视频请适当延长轮询周期与超时时间。

## 常见问题

<AccordionGroup>
  <Accordion title="怎么从百炼官方迁移到网关？">
    把请求域名从 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 换成 `https://api.looprouter.com`，把 `Authorization` 里的百炼 API Key 换成 LoopRouter 的 `sk-` 令牌即可。路径 `/api/v1/services/aigc/video-generation/video-synthesis` 与 `/api/v1/tasks/{task_id}`、请求体与响应结构都保持不变，无需业务空间 ID。
  </Accordion>
  <Accordion title="为什么创建任务只返回 task_id，没有视频？">
    这是异步任务接口：创建仅入队并返回 `output.task_id`，需轮询 `GET /api/v1/tasks/{task_id}` 直到 `task_status` 变为 `SUCCEEDED`，再从 `output.video_url` 下载成片。
  </Accordion>
  <Accordion title="成功状态是什么？">
    是 `SUCCEEDED`（全大写）。终态请匹配 `SUCCEEDED / FAILED / CANCELED`；`UNKNOWN` 表示任务不存在或已过查询有效期。
  </Accordion>
  <Accordion title="支持哪些分辨率？为什么不能用 4K？">
    万相 3.0 支持 `480P` / `720P` / `1080P` 三档，默认 `1080P`。官方未提供更高档位，传入其他值会返回参数错误且不扣费。
  </Accordion>
  <Accordion title="能用智能时长（duration = -1）吗？">
    网关**不支持** `-1`。因为提交时真实时长未知，无法按秒预扣，会导致少收费。请传 2–30 秒的明确整数；有视频输入时确保「输入 + 输出 ≤ 30 秒」。
  </Accordion>
  <Accordion title="reference_xx 和 first_frame 能一起传吗？">
    不能。`first_frame` / `last_frame` 与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link` 互斥，混用会返回 `The two modes are mutually exclusive` 错误。
  </Accordion>
  <Accordion title="视频链接过期了怎么办？">
    `output.video_url` 是临时链接，任务成功后请尽快下载并转存到自己的存储；过期后可重新调用查询接口获取新链接，但任务本身也有保留期限。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/wan3/video-generation">
    参数、media 数组与响应详解
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    llms.txt 与推荐提示词
  </Card>
</CardGroup>