> ## Documentation Index
> Fetch the complete documentation index at: https://docs.token.poryf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 万相 3.0

> 万相 3.0 视频生成：文生视频与首尾帧图生视频的参数、示例与计费。

阿里通义万相 3.0 视频模型，支持文生视频、首帧 / 首尾帧图生视频，以及用图片、视频、音频作参考的多模态生成。`wan3.0-video-prime` 是旗舰版，画质更好；`wan3.0-video` 是标准版，价格更低。

* 模型 ID：`wan3.0-video-prime`、`wan3.0-video`（参数与用法相同）
* 接口：`POST https://token.poryf.com/v1/videos`（异步任务）
* [查看价格](https://token.poryf.com/pricing/wan3.0-video-prime) · [在线试用](https://token.poryf.com/model-guide/wan3.0-video-prime)（登录后，按自己的余额扣费）

## 请求参数

**Authorization** `string` *required*

`Bearer YOUR_API_KEY`，在 [控制台的 API 密钥页](https://token.poryf.com/keys) 创建。

**model** `string` *required*

`wan3.0-video-prime`、`wan3.0-video`

**prompt** `string`

画面与运动描述。文生视频必填；图生视频建议填写。

**seconds** `integer` (default: 5)

时长：2–30 秒的整数，默认 5；传 `-1` 由模型自动决定时长。

**resolution** `string` (default: 1080P)

`480P`、`720P`、`1080P`。不传默认 `1080P`，在线试用默认 `720P`。

**ratio** `string` (default: adaptive)

画面比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`adaptive`。`adaptive` 跟随首帧图片，

**images** `string[]`

首帧 / 首尾帧图片的公网 URL：第一张为首帧，第二张为尾帧。可选，不传即文生视频。

**negative\_prompt** `string`

不希望出现的内容。

**seed** `integer`

随机种子。

**prompt\_extend** `boolean` (default: true)

是否由模型自动改写、扩充提示词。

**metadata.input.media** `object[]`

多模态参考素材，每项形如 `{"type": "reference_image", "url": "https://..."}`。`type` 取值：`reference_image`（最多 10 张）、`reference_video`（最多 5 个）、`reference_audio`（最多 5 个）。传了它就不要再传 `images`：参考素材和首尾帧不能混用。

> [!WARNING]
>
> * 图片、视频、音频请使用公网可访问的 `http(s)` URL，不要上传文件或使用 Base64。
> * 视频生成通常需要 1–3 分钟，请轮询查询任务状态。

## 示例：文生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-prime",
    "prompt": "清晨的海边，一只柯基在沙滩上奔跑，镜头缓慢跟随",
    "seconds": 5,
    "resolution": "720P",
    "ratio": "16:9"
  }'
```

## 示例：首尾帧图生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-prime",
    "prompt": "花朵从含苞到完全绽放",
    "seconds": 5,
    "resolution": "720P",
    "images": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }'
```

只传一张图即为首帧图生视频。

## 示例：多模态参考

用参考图确定人物形象，用参考视频确定动作和运镜：

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-prime",
    "prompt": "参考图片中的人物，按照参考视频的动作在城市街头跳舞",
    "seconds": 8,
    "resolution": "720P",
    "ratio": "9:16",
    "metadata": {
      "input": {
        "media": [
          {"type": "reference_image", "url": "https://example.com/person.png"},
          {"type": "reference_video", "url": "https://example.com/dance.mp4"}
        ]
      }
    }
  }'
```

## 响应

提交成功后返回任务对象（示例结构）：

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "queued",
  "progress": 0
}
```

查询进度、下载视频的方法见 [视频通用说明](https://docs.token.poryf.com/api/videos/overview.md#查询进度)。

## 计费

按秒计费，单价按输出分辨率（480P / 720P / 1080P）分档。实时单价见 [模型广场](https://token.poryf.com/pricing)。

* 生成视频：按输出时长计费。
* 参考视频：按参考视频时长计费，单价与所选分辨率的生成单价相同。
* 图片和音频参考：不单独计费。

提交时先预扣：时长按请求的 `seconds`（不传按 5 秒）；`seconds` 为 `-1` 或带参考视频时按 30 秒预扣。任务完成后按实际时长多退少补；任务失败自动全额退回。

## 常见错误

| 出现时机 | 错误 | 原因 |
| - | - | - |
| 提交时返回错误 | `wan3.0-video-prime duration must be -1 or an integer between 2 and 30` | `seconds` 超出范围 |
| 提交时返回错误 | `wan3.0-video-prime resolution must be one of 480P, 720P, 1080P` | 分辨率写成了其他档位 |
| 提交时返回错误 | `unsupported wan3.0 input.media combination` | 首尾帧和参考素材混用，或只传了尾帧 |

其他错误见 [视频通用说明](https://docs.token.poryf.com/api/videos/overview.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.