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

# 万相 2.5 视频生成

> 阿里万相 Wan 2.5 文生视频、图生视频

## 简介

万相 2.5（Wan 2.5）是阿里云百炼推出的视频生成系列，由文生视频（`wan2.5-t2v-preview`）与图生视频（`wan2.5-i2v-preview`）组成，支持 **480P**、**720P** 与 **1080P** 输出。

通过 GravitexAI 统一视频接口调用：先 [提交视频任务](/cn/api-reference/endpoint/submit-video-task) 获取任务 `id`，再 [查询视频任务](/cn/api-reference/endpoint/query-video-task) 轮询状态并获取视频 URL。

<Note>
  万相 2.5 的推荐请求体通过 `metadata.input` 与 `metadata.parameters` 传递底层 DashScope 参数。顶层 `prompt`、`duration` 等字段用于兼容展示，**实际生效以 `metadata.parameters` 为准**。
</Note>

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxx`
</ParamField>

## 支持的模型

| 模型 ID                | 说明   | 支持分辨率           | 特点        |
| -------------------- | ---- | --------------- | --------- |
| `wan2.5-t2v-preview` | 文生视频 | 480P、720P、1080P | 文本提示词生成视频 |
| `wan2.5-i2v-preview` | 图生视频 | 480P、720P、1080P | 首帧图像驱动生成  |

## 调用流程

1. **提交任务**：`POST /v1/video/generations`，传入 `model`、`prompt` 及 `metadata` 中的万相参数。
2. **轮询状态**：`GET /llm-api/v1/video/generations/{id}`（域名 `maas.gravitex.ai`），建议每 3–15 秒查询一次，直到 `data.status` 为 `completed` 或 `failed`。
3. **获取结果**：成功时从 `data.url`、`data.video_url` 或 `data.metadata.output.video_url` 获取视频地址（通常为临时链接，请及时下载转存）。

## 通用请求结构

| 字段                    | 类型      | 必填 | 说明                                                                             |
| --------------------- | ------- | -- | ------------------------------------------------------------------------------ |
| `model`               | string  | 是  | 模型 ID，见上表                                                                      |
| `prompt`              | string  | 建议 | 视频生成提示词，建议与 `metadata.input.prompt` 保持一致                                       |
| `duration`            | integer | 否  | 顶层时长；若与 `metadata.parameters.duration` 不一致，以 `metadata.parameters.duration` 为准 |
| `metadata.input`      | object  | 是  | 输入：`prompt`、`img_url`（图生视频）等                                                   |
| `metadata.parameters` | object  | 建议 | 处理参数：`resolution`、`ratio`、`duration`、`prompt_extend`、`watermark`、`seed` 等      |

### 提交成功响应

提交接口返回 OpenAI Video 风格对象，使用 `id` 作为后续查询的任务 ID：

```json theme={null}
{
  "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
  "object": "video",
  "model": "wan2.5-i2v-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1781767983,
  "metadata": {
    "output": {
      "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
      "task_status": "PENDING"
    },
    "request_id": "2a17a551-0db2-910d-988b-7d5abed99d2d"
  }
}
```

### 查询成功响应

查询接口返回统一包装结构，`data.status` 为 `completed` 时表示成功：

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
    "object": "video",
    "model": "wan2.5-i2v-preview",
    "status": "completed",
    "progress": 100,
    "seconds": "3",
    "url": "https://xxx.mp4",
    "video_url": "https://xxx.mp4",
    "created_at": 1781767983,
    "completed_at": 1781768013,
    "metadata": {
      "output": {
        "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
        "task_status": "SUCCEEDED",
        "orig_prompt": "生成吃草小羊\n",
        "video_url": "https://xxx.mp4",
        "submit_time": "2026-06-18 15:33:03.266",
        "scheduled_time": "2026-06-18 15:33:03.285",
        "end_time": "2026-06-18 15:33:32.407"
      },
      "usage": {
        "SR": 480,
        "duration": 3,
        "video_count": 1
      },
      "url": "https://xxx.mp4",
      "video_url": "https://xxx.mp4"
    }
  }
}
```

## 使用场景

<Tabs>
  <Tab title="文生视频 (T2V)">
    基于文本提示词生成视频，支持智能改写 prompt、自定义分辨率与宽高比。

    <ParamField body="metadata.input.prompt" type="string" required>
      文本提示词，建议与顶层 `prompt` 保持一致
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`、`720P` 或 `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      宽高比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      视频时长（秒），常见取值如 3、5、10
    </ParamField>

    <ParamField body="metadata.parameters.prompt_extend" type="boolean" default="true">
      是否开启 Prompt 智能改写
    </ParamField>

    <ParamField body="metadata.parameters.watermark" type="boolean" default="false">
      是否添加水印
    </ParamField>

    <ParamField body="metadata.parameters.seed" type="integer">
      随机种子，范围 `[0, 2147483647]`
    </ParamField>

    **文生视频示例：**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-t2v-preview",
        "prompt": "一只小猫慢慢睁开眼睛，耳朵轻轻抖动，镜头慢慢推进",
        "metadata": {
          "input": {
            "prompt": "一只小猫慢慢睁开眼睛，耳朵轻轻抖动，镜头慢慢推进"
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="图生视频 (I2V)">
    基于首帧图像生成视频，通过 `metadata.input.img_url` 传入首帧图片地址。

    <ParamField body="metadata.input.img_url" type="string" required>
      首帧图片 URL
    </ParamField>

    <ParamField body="metadata.input.prompt" type="string" required>
      文本提示词，建议与顶层 `prompt` 保持一致
    </ParamField>

    <ParamField body="metadata.input.media" type="array">
      可选，描述输入媒体类型，例如 `[{"type": "reference_image"}]`
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`、`720P` 或 `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      宽高比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      视频时长（秒），常见取值如 3、5、10
    </ParamField>

    <ParamField body="metadata.parameters.prompt_extend" type="boolean" default="true">
      是否开启 Prompt 智能改写
    </ParamField>

    <ParamField body="metadata.parameters.watermark" type="boolean" default="false">
      是否添加水印
    </ParamField>

    **图生视频示例：**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-i2v-preview",
        "prompt": "生成吃草小羊",
        "metadata": {
          "input": {
            "img_url": "https://example.com/first_frame.png",
            "prompt": "生成吃草小羊",
            "media": [
              {"type": "reference_image"}
            ]
          },
          "parameters": {
            "resolution": "480P",
            "ratio": "16:9",
            "duration": 3,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## 参数参考

### metadata.parameters

| 参数              | 类型      | 说明                              |
| --------------- | ------- | ------------------------------- |
| `duration`      | integer | 实际生效的视频时长（秒）                    |
| `resolution`    | string  | `480P`、`720P` 或 `1080P`         |
| `ratio`         | string  | `16:9`、`9:16`、`1:1`、`4:3`、`3:4` |
| `prompt_extend` | boolean | 是否智能改写 Prompt，默认 `true`         |
| `watermark`     | boolean | 是否添加水印，默认 `false`               |
| `seed`          | integer | 随机种子，范围 `[0, 2147483647]`       |

### metadata.input

| 参数        | 类型     | 适用场景      | 说明          |
| --------- | ------ | --------- | ----------- |
| `prompt`  | string | T2V / I2V | 上游实际使用的提示词  |
| `img_url` | string | I2V       | 首帧图片地址      |
| `media`   | array  | I2V       | 可选，描述输入媒体类型 |

### 查询响应关键字段

| 字段                                 | 说明                                                 |
| ---------------------------------- | -------------------------------------------------- |
| `data.status`                      | 统一任务状态：`queued`、`in_progress`、`completed`、`failed` |
| `data.seconds`                     | 最终视频秒数（字符串）                                        |
| `data.url` / `data.video_url`      | 视频下载地址                                             |
| `data.metadata.output.task_status` | 上游原始状态，如 `SUCCEEDED`                               |
| `data.metadata.usage.SR`           | 分辨率档位，如 `480`、`720`                                |
| `data.metadata.usage.duration`     | 最终计费/产出时长                                          |

## 状态映射

| 上游状态                              | 查询接口 `data.status` |
| --------------------------------- | ------------------ |
| `PENDING`                         | `queued`           |
| `RUNNING`                         | `in_progress`      |
| `SUCCEEDED`                       | `completed`        |
| `FAILED` / `CANCELED` / `UNKNOWN` | `failed`           |

## 错误处理

| HTTP 状态码 | 含义     | 建议                    |
| -------- | ------ | --------------------- |
| 400      | 请求参数错误 | 检查 `metadata` 结构与媒体限制 |
| 401      | 未授权    | 检查 API Key            |
| 429      | 请求过于频繁 | 降低频率后重试               |
| 502      | 上游服务错误 | 稍后重试                  |

任务失败时，`data.status` 为 `failed`，可结合 `data.metadata.output.task_status` 排查原因。

## 常见问题

<AccordionGroup>
  <Accordion title="顶层 duration 和 metadata.parameters.duration 不一致怎么办？">
    以 **`metadata.parameters.duration`** 为准。建议正式接入时要么不传顶层 `duration`，要么保证两者完全一致，避免理解偏差。
  </Accordion>

  <Accordion title="prompt 需要传几次？">
    建议顶层 `prompt` 与 `metadata.input.prompt` **保持一致**，便于查询结果中的 `orig_prompt` 与请求对齐。
  </Accordion>

  <Accordion title="生成的视频链接有效期多久？">
    查询成功后拿到的 `video_url` 一般为临时 OSS 链接，建议获取后立即下载并转存至自有存储。
  </Accordion>

  <Accordion title="如何判断任务成功？">
    建议按以下优先级判断：

    1. `data.status == "completed"`
    2. `data.video_url` 或 `data.url` 非空
    3. `data.metadata.output.task_status == "SUCCEEDED"`
  </Accordion>

  <Accordion title="与万相 2.7 的调用方式有何不同？">
    万相 2.5 仅支持文生视频与图生视频（首帧），图生视频使用 `metadata.input.img_url` 而非 2.7 的 `media` 数组；万相 2.7 额外支持参考生视频、视频续写、首尾帧等能力。详见 [万相 2.7](/cn/api-reference/endpoint/wan2.7)。
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns cols={2}>
  <Card title="提交视频任务" icon="upload" href="/cn/api-reference/endpoint/submit-video-task">
    统一视频任务提交入口与多模型参数说明
  </Card>

  <Card title="查询视频任务" icon="search" href="/cn/api-reference/endpoint/query-video-task">
    轮询任务状态并获取视频 URL
  </Card>
</Columns>