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

# 万相 3.0 视频生成接口

> 通过万相 3.0 All-in-One 模型生成、编辑和延长原生有声视频

万相 3.0 使用 All-in-One 模型：根据 `input.media` 中的素材类型及提示词意图，自动处理文生视频、首帧或首尾帧图生视频、全模态参考生成、视频编辑和视频延长。与 [万相 2.7 视频生成接口](/docs/zh/api-reference/video/wan) 不同，3.0 无需为不同能力选择独立的文生、图生或编辑模型。

接口沿用万相视频任务协议。无需携带 `X-DashScope-Async` 请求头，网关已内置异步任务语义。

## 请求结构

请求体由 `model`、`input` 和 `parameters` 三部分组成：

| 字段             | 必填                     | 说明                                                          |
| -------------- | ---------------------- | ----------------------------------------------------------- |
| `model`        | 是                      | 平台模型标识：`wan3.0-video` 或 `wan3.0-video-prime`                |
| `input.prompt` | 与 `input.media` 至少传一个  | 文本提示词，最长 20,000 个字符。全模态参考模式中可用“图1”“视频1”“音频1”等名称引用数组中对应顺序的素材 |
| `input.media`  | 与 `input.prompt` 至少传一个 | 媒体素材数组；每项都包含 `type` 和 `url`                                 |
| `parameters`   | 否                      | 输出分辨率、比例、时长、音频、随机种子、提示词扩写和水印等生成参数                           |

`media[].url` 可使用可公开访问的 HTTP/HTTPS URL、OSS 临时 URL 或 base64 data URI。使用 base64 data URI 时，网关会先将素材转存后再提交给上游。

## 认证方式

在请求头中携带 `Authorization`，格式为 `Bearer YOUR_API_KEY`。

## 支持的模型

| 模型标识                 | 说明                           |
| -------------------- | ---------------------------- |
| `wan3.0-video`       | 万相 3.0 通用 All-in-One 视频模型    |
| `wan3.0-video-prime` | 万相 3.0 Prime All-in-One 视频模型 |

## 能力与素材类型

万相 3.0 可以生成带原生同步声音的视频，最长 30 秒。通过 `input.media` 提供素材：

| `type`            | 用途         | 限制与说明                                                             |
| ----------------- | ---------- | ----------------------------------------------------------------- |
| `first_frame`     | 首帧图生视频     | 最多 1 张；可与 `last_frame` 组成首尾帧模式                                    |
| `last_frame`      | 尾帧图生视频     | 最多 1 张；只能与 `first_frame` 一起使用                                     |
| `reference_image` | 参考图        | 最多 10 张，单张不超过 20 MB                                               |
| `reference_video` | 参考、编辑或延长视频 | 最多 5 个；总时长不超过 15 秒，单个不超过 100 MB，帧率至少 16 fps                       |
| `reference_audio` | 参考音频       | 最多 5 个；总时长不超过 15 秒，单个不超过 15 MB                                    |
| `file`            | 文档参考       | 最多 1 个，支持 `docx`、`doc`、`xlsx`、`xls`、`pptx`、`ppt`、`pdf`、`txt`、`md` |
| `link`            | 公开网页参考     | 最多 1 个；网页必须可公开访问且无需登录                                             |

<Note>
  `first_frame` / `last_frame` 与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link` 互斥，不能出现在同一请求中。`file` 和 `link` 二选一，但都可以与参考图、参考视频和参考音频组合使用；三个 `reference_*` 类型可以自由组合。
</Note>

首帧或首尾帧模式仅能传入 `first_frame` 和可选的 `last_frame`，不能同时传入音频等其他媒体。需要用声音驱动画面时，请使用全模态参考模式，例如 `reference_image` 加 `reference_audio`。

## 关键参数

| 参数              | 默认值        | 说明                                                                              |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `resolution`    | `1080P`    | 输出分辨率：`480P`、`720P` 或 `1080P`                                                   |
| `ratio`         | `adaptive` | 画面比例：`16:9`、`4:3`、`1:1`、`3:4`、`9:16` 或 `adaptive`。`adaptive` 会根据输入媒体比例和意图自动推荐比例 |
| `duration`      | `5`        | 输出时长（秒）。没有视频输入时可设为 `2` 到 `30`；有视频输入时，输入视频总时长加输出时长不能超过 30 秒。设为 `-1` 启用智能时长       |
| `audio`         | `true`     | 是否保留输出音轨。`true` 生成原生同步声音；`false` 不生成音轨，两种设置价格相同                                 |
| `seed`          | `-1`       | 随机种子。可设为 `-1` 或 `0` 到 `2147483647`；省略或设为 `-1` 时系统自动生成。相同种子不能保证每次结果完全一致          |
| `prompt_extend` | `true`     | 是否智能扩写提示词。短提示词开启后通常会改善效果，但会增加耗时。使用 `file` 或 `link` 时必须开启或省略，不能设为 `false`        |
| `watermark`     | `false`    | 是否添加水印标识                                                                        |

对于视频编辑，使用 `reference_video` 并在提示词中明确说明替换、删除或修改的目标。对于视频延长，在提示词中说明延长、续写、向前或向后延伸等意图。编辑或延长视频时，建议使用 `ratio: "adaptive"` 和 `duration: -1`。

## 快速提交

下面以文生视频为例。创建成功后使用响应中的 `output.task_id` 查询任务结果。

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.haitoken.ai/v1/alibaba/video/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "wan3.0-video",
          "input": {
              "prompt": "一只金毛犬在日落的海边奔跑，镜头缓慢跟随，海浪声清晰可闻。"
          },
          "parameters": {
              "resolution": "720P",
              "ratio": "16:9",
              "duration": 5,
              "prompt_extend": True,
          },
      },
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.haitoken.ai/v1/alibaba/video/generations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'wan3.0-video',
      input: {
        prompt: 'A golden retriever runs along the beach at sunset; the camera follows slowly; ocean waves are clearly audible.'
      },
      parameters: {
        resolution: '720P',
        ratio: '16:9',
        duration: 5,
        prompt_extend: true
      }
    })
  });

  console.log(await response.json());
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://api.haitoken.ai/v1/alibaba/video/generations' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "wan3.0-video",
      "input": {
        "prompt": "一只金毛犬在日落的海边奔跑，镜头缓慢跟随，海浪声清晰可闻。"
      },
      "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5,
        "prompt_extend": true
      }
    }'
  ```
</CodeGroup>

## 场景示例

### 首尾帧图生视频

首尾帧模式只放入首帧和尾帧，不要混入 `reference_*`、`file` 或 `link`。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "镜头从清晨的空旷街道平稳推进，最后定格在咖啡馆门口，保持电影感光影。",
    "media": [
      {
        "type": "first_frame",
        "url": "https://example.com/first-frame.jpg"
      },
      {
        "type": "last_frame",
        "url": "https://example.com/last-frame.jpg"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 5,
    "prompt_extend": true
  }
}
```

### 文件参考生成

`file` 最多传一个，且不能与 `link` 一起使用。该模式必须开启或省略 `prompt_extend`。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "根据文件中的产品卖点生成 10 秒高端智能眼镜广告，黑色、银灰色和冰蓝色为主色调。",
    "media": [
      {
        "type": "file",
        "url": "https://example.com/product-brief.pdf"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 10,
    "prompt_extend": true
  }
}
```

### 网页与参考图生成

`link` 使用公开且无需登录的网页。它可以与 `reference_image` 等参考媒体组合。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "参考网页中的产品信息和图1的外观，制作简洁的产品发布短片。",
    "media": [
      {
        "type": "link",
        "url": "https://example.com/product-page"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/product-reference.jpg"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 8,
    "prompt_extend": true
  }
}
```

### 全模态参考生成

参考图、参考视频和参考音频可组合使用。数组中图、视频和音频分别按出现顺序编号。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "让图1中的人物在视频1的海边场景中向镜头走来，使用音频1的语音和节奏，画面自然真实。",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/person.jpg"
      },
      {
        "type": "reference_video",
        "url": "https://example.com/beach.mp4"
      },
      {
        "type": "reference_audio",
        "url": "https://example.com/voice.wav"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 5,
    "prompt_extend": true
  }
}
```

### 视频编辑

使用 `reference_video`，并把编辑目标直接写进提示词。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "将视频中的天空修改为黄昏色调，保留人物动作和原有对话。",
    "media": [
      {
        "type": "reference_video",
        "url": "https://example.com/input-video.mp4"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": -1,
    "prompt_extend": true
  }
}
```

### 视频延长

使用 `reference_video`，并明确说明续写方向或后续画面。

```json theme={null}
{
  "model": "wan3.0-video",
  "input": {
    "prompt": "将视频向后延长，镜头继续向右平移，展现更广阔的山间风景并补充自然环境声。",
    "media": [
      {
        "type": "reference_video",
        "url": "https://example.com/input-video.mp4"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": -1,
    "prompt_extend": true
  }
}
```

创建成功后会返回任务 ID：

```json theme={null}
{
  "request_id": "8f3d2c1a-9b7e-4f5a-8c2d-1e6f0a9b3c5d",
  "output": {
    "task_id": "cgt-20260730120000-a1b2c3",
    "task_status": "PENDING"
  }
}
```

## 下一步

* 查看 [查询万相视频任务](/docs/zh/api-reference/video/wan-status) 获取生成结果
* 对比 [万相 2.7 视频生成接口](/docs/zh/api-reference/video/wan) 了解版本差异
* 查看 [视频生成](/docs/zh/api-reference/video/generation) 了解统一协议
* 查看 [模型列表](/docs/zh/api-reference/models/list-models) 了解可用的视频模型


## OpenAPI

````yaml zh/api-reference/video/wan3/openapi.json POST /v1/alibaba/video/generations
openapi: 3.0.1
info:
  title: 万相 3.0 视频生成
  version: 1.0.0
servers:
  - url: https://api.haitoken.ai
security: []
paths:
  /v1/alibaba/video/generations:
    post:
      summary: 创建万相 3.0 视频任务
      description: 使用万相 3.0 All-in-One 模型创建异步视频任务。无需携带 X-DashScope-Async 请求头，网关已内置异步任务语义。
      parameters:
        - name: Authorization
          in: header
          description: API Key，格式为 Bearer YOUR_API_KEY
          required: true
          schema:
            type: string
            example: Bearer YOUR_API_KEY
        - name: Content-Type
          in: header
          description: 请求体类型
          required: true
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlibabaCreateTaskRequest'
      responses:
        '200':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlibabaCreateTaskResponse'
              example:
                request_id: 8f3d2c1a-9b7e-4f5a-8c2d-1e6f0a9b3c5d
                output:
                  task_id: cgt-20260730120000-a1b2c3
                  task_status: PENDING
components:
  schemas:
    AlibabaCreateTaskRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: 万相 3.0 All-in-One 模型标识：wan3.0-video 或 wan3.0-video-prime
        input:
          $ref: '#/components/schemas/Input'
          description: 输入内容（提示词与媒体元素）
        parameters:
          $ref: '#/components/schemas/Parameters'
          description: 生成参数
    AlibabaCreateTaskResponse:
      type: object
      properties:
        request_id:
          type: string
          description: 网关请求 ID
        output:
          type: object
          properties:
            task_id:
              type: string
              description: 用于查询任务状态的任务 ID
            task_status:
              type: string
              enum:
                - PENDING
              description: 任务状态
    Input:
      type: object
      anyOf:
        - required:
            - prompt
        - required:
            - media
      properties:
        prompt:
          type: string
          maxLength: 20000
          description: >-
            文本提示词。描述要生成、编辑或延长的视频内容；与 media
            至少传入一个。全模态参考模式可用“图1”“视频1”“音频1”等名称引用按数组顺序提供的素材
        media:
          type: array
          description: 媒体元素列表（首帧/尾帧/参考图/参考视频/参考音频/文件/网页链接）
          items:
            $ref: '#/components/schemas/MediaItem'
    Parameters:
      type: object
      properties:
        resolution:
          type: string
          enum:
            - 480P
            - 720P
            - 1080P
          default: 1080P
          description: 输出分辨率档位
        ratio:
          type: string
          enum:
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
            - adaptive
          default: adaptive
          description: 输出画面比例。使用输入媒体时推荐 adaptive
        duration:
          type: integer
          oneOf:
            - enum:
                - -1
            - minimum: 2
              maximum: 30
          default: 5
          description: 输出时长（秒）。无视频输入时为 2 至 30；有视频输入时，输入视频总时长与输出时长之和不能超过 30。-1 为智能时长
        prompt_extend:
          type: boolean
          default: true
          description: 是否自动扩写提示词。开启后会优化短提示词效果，但会增加耗时。使用 file 或 link 时不能设为 false
        audio:
          type: boolean
          default: true
          description: 是否输出原生同步声音。默认开启，设为 false 可关闭（开关声音价格相同）
        watermark:
          type: boolean
          default: false
          description: 是否带水印
        seed:
          type: integer
          format: int64
          minimum: -1
          maximum: 2147483647
          default: -1
          description: 随机种子。可设为 -1 或 0 至 2147483647；省略或设为 -1 时由系统自动生成。相同种子不能保证每次生成结果完全一致
    MediaItem:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          description: >-
            素材类型。first_frame 首帧 / last_frame 尾帧 / reference_image 参考图 /
            reference_video 参考、编辑或延长视频 / reference_audio 参考音频 / file 参考文件（与 link
            互斥）/ link 网页链接（与 file 互斥）
        url:
          type: string
          format: uri
          description: 媒体 URL 或 base64 data URI（base64 由网关转存 OBS 后替换为 URL）

````