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

# Wan 2.7 视频生成 API

> Wan 2.7 视频生成接口开发文档：通过 LaoZhang API 调用 DashScope 兼容异步任务接口，支持文生视频、图生视频、参考图生视频和视频编辑。

## 接入概览

<Info>
  本文定义 Wan 视频生成在 LaoZhang API 上的开发接入方式。接口采用 DashScope 兼容异步任务协议：客户端先创建任务并获取 `task_id`，再轮询任务状态，任务完成后从 `result_url` 下载 MP4 文件。
</Info>

<Warning>
  Wan 视频生成不使用 Sora / Veo 的 `/v1/videos` 接口。Wan 2.7 的图生视频、参考图生视频和视频编辑依赖 DashScope 原生 `input.media[]` 结构，请固定使用本文的 `/wan/api/v1/services/aigc/video-generation/video-synthesis` 创建任务路径。
</Warning>

## 认证与令牌

在 [令牌管理](https://api.laozhang.ai/token) 创建用于 Wan 视频生成的令牌时，按下面配置：

| 配置项    | 选择                                           |
| ------ | -------------------------------------------- |
| 控制台入口  | [令牌管理](https://api.laozhang.ai/token) → 新增令牌 |
| 选择分组   | `Wan`                                        |
| 计费模式   | `按量扣费`                                       |
| Header | `Authorization: Bearer YOUR_API_KEY`         |
| 建议     | 为 Wan 视频单独创建令牌，便于按模型、任务和调用日志核对消费             |

<Warning>
  Wan 视频请求必须使用 `Wan` 分组、按量扣费的令牌。默认分组、Veo 分组、Sora 分组或其他视频分组的令牌可能返回无可用渠道、模型不匹配或计费分组错误。
</Warning>

## 计费与价格

<Info>
  以下为上游官方公开价格口径，用于接入前成本预估。LaoZhang API 实际扣费以控制台模型价格和调用日志为准。当前控制台中 `Wan` 分组显示倍率 `0.15x`；该数值是上游人民币价格与本站美元计价口径之间的换算系数。按固定汇率 `1:7` 计算，`0.15 × 7 = 1.05`，即当前价格约为阿里云官方人民币原价的 `105%`。`0.15x` 不是需要在调用日志“实际扣除”金额上再次相乘的额外折扣。
</Info>

官方参考：[阿里云百炼模型价格](https://help.aliyun.com/zh/model-studio/model-pricing)。

| 请求形态               | 官方计费口径                 | 720P 官方价  | 1080P 官方价 |
| ------------------ | ---------------------- | --------- | --------- |
| 文生视频、仅图像/音频输入的图生视频 | 按成功生成的输出视频秒数计费；失败不计费   | `0.6 元/秒` | `1 元/秒`   |
| 参考生视频中包含输入视频       | 输入视频计费时长 + 输出视频时长，按秒计费 | `0.6 元/秒` | `1 元/秒`   |
| 视频编辑               | 输入视频时长 + 输出视频时长，按秒计费   | `0.6 元/秒` | `1 元/秒`   |

<Note>
  `duration` 和 `resolution` 会直接影响费用。生产环境应在创建任务前完成成本预估，并在任务完成后按控制台调用日志核对实际扣费。
</Note>

## 调用流程

<Steps>
  <Step title="创建任务">
    调用 `POST /wan/api/v1/services/aigc/video-generation/video-synthesis`。请求体使用 JSON，`model` 传 Wan 模型 ID，`input.prompt` 传提示词，图生视频、参考图生视频和视频编辑通过 `input.media[]` 传素材。
  </Step>

  <Step title="轮询状态">
    调用 `GET /v1/tasks/{task_id}`。客户端只需要根据顶层 `status` 字段判断状态，不要解析内部上游字段作为业务状态。
  </Step>

  <Step title="下载结果">
    当 `status=completed` 时，读取顶层 `result_url` 并直接下载。`result_url` 是上游对象存储签名 URL，下载请求不要携带 LaoZhang API 的 `Authorization` 头。
  </Step>
</Steps>

## API 参考

### 请求约定

| 配置项           | 值                                    |
| ------------- | ------------------------------------ |
| Base URL      | `https://api.laozhang.ai`            |
| 认证方式          | `Authorization: Bearer YOUR_API_KEY` |
| 创建请求格式        | `application/json`                   |
| 创建任务必需 Header | `X-DashScope-Async: enable`          |
| 轮询间隔          | 建议 5-10 秒                            |
| 客户端超时         | 建议 20 分钟                             |

### 端点

| 用途     | 方法     | 路径                                                           |
| ------ | ------ | ------------------------------------------------------------ |
| 创建视频任务 | `POST` | `/wan/api/v1/services/aigc/video-generation/video-synthesis` |
| 查询任务状态 | `GET`  | `/v1/tasks/{task_id}`                                        |
| 下载视频   | `GET`  | 任务完成后返回的 `result_url`                                        |

### 状态机

| 状态            | 是否终态 | 客户端处理                                     |
| ------------- | ---- | ----------------------------------------- |
| `submitted`   | 否    | 任务已提交，继续轮询                                |
| `in_progress` | 否    | 任务生成中，继续轮询                                |
| `completed`   | 是    | 读取 `result_url` 下载 MP4                    |
| `failed`      | 是    | 读取 `error.message` 或 `fail_reason`，不要继续轮询 |

<Note>
  Wan / DashScope 的 `progress` 是粗粒度上报，常见情况是长时间停在 `30%`，最后直接跳到 `100%`。只要 `status` 仍是 `in_progress`，通常继续等待即可。
</Note>

## 模型与输入模式

| 模型 ID                                                                                            | 能力              | `input.media[]` 要求                      |
| ------------------------------------------------------------------------------------------------ | --------------- | --------------------------------------- |
| `wan2.7-t2v`                                                                                     | 文生视频            | 不传 `media`                              |
| `wan2.7-i2v`                                                                                     | 图生视频，可配驱动音频     | 至少 1 个 `first_frame`；可选 `driving_audio` |
| `wan2.7-r2v`                                                                                     | 参考图生视频          | 1 个或多个 `reference_image`                |
| `wan2.7-videoedit`                                                                               | 视频编辑            | 1 个 `video` + 1 个或多个 `reference_image`  |
| `wan2.6-t2v` / `wan2.6-i2v` / `wan2.6-r2v` / `wan2.6-r2v-flash`                                  | Wan 2.6 系列      | 与同能力 Wan 2.7 模型一致                       |
| `happyhorse-1.0-t2v` / `happyhorse-1.0-i2v` / `happyhorse-1.0-r2v` / `happyhorse-1.0-video-edit` | HappyHorse 视频模型 | 与同能力模型一致，具体素材数量按模型能力限制                  |

<Warning>
  `wan2.7-image-pro` 是图片模型，不属于本文的视频生成端点。请不要把它提交到 `/wan/api/v1/services/aigc/video-generation/video-synthesis`。
</Warning>

## 请求体

### 顶层字段

| 字段           | 类型     | 必填 | 说明                    |
| ------------ | ------ | -- | --------------------- |
| `model`      | string | 是  | 模型 ID，例如 `wan2.7-t2v` |
| `input`      | object | 是  | 输入对象，包含提示词和媒体素材       |
| `parameters` | object | 否  | 生成参数，例如分辨率、时长、水印      |

### `input`

| 字段       | 类型     | 必填    | 说明                                   |
| -------- | ------ | ----- | ------------------------------------ |
| `prompt` | string | 是     | 自然语言提示词                              |
| `media`  | array  | 按模型而定 | 素材数组；t2v 不传，i2v / r2v / videoedit 必填 |

### `input.media[]`

| `type`            | 用途                          |
| ----------------- | --------------------------- |
| `first_frame`     | 图生视频首帧图片                    |
| `last_frame`      | 尾帧图片，按模型能力使用                |
| `reference_image` | 参考图片，可用于 r2v 或视频编辑          |
| `driving_audio`   | 驱动音频，常用于 `wan2.7-i2v`       |
| `video`           | 输入视频，常用于 `wan2.7-videoedit` |

<Warning>
  媒体素材 URL 必须是公网可访问的 HTTPS 直链。需要登录、带 Cookie、内网地址或临时不可访问的链接会导致任务失败。
</Warning>

### `parameters`

| 字段              | 类型      | 推荐值        | 说明                                      |
| --------------- | ------- | ---------- | --------------------------------------- |
| `resolution`    | string  | `720P`     | 可用值通常为 `480P`、`720P`、`1080P`；建议使用大写 `P` |
| `duration`      | integer | `5` 或 `10` | 视频时长，传整数，不要传字符串                         |
| `prompt_extend` | boolean | `true`     | 是否启用上游提示词扩写                             |
| `watermark`     | boolean | `true`     | 是否添加 AI 生成水印                            |
| `seed`          | integer | 可选         | 随机种子，传整数                                |

## 环境变量

后续示例统一使用以下变量：

```bash theme={null}
export BASE_URL="https://api.laozhang.ai"
export API_KEY="YOUR_API_KEY"
```

## 文生视频

```bash theme={null}
curl -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，海鸟叫声，电影级光影，稳定运镜"
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "prompt_extend": true,
      "watermark": true
    }
  }'
```

创建成功返回 DashScope 兼容的任务对象。客户端应保存 `output.task_id`：

```json theme={null}
{
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "PENDING"
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## 图生视频

```bash theme={null}
curl -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-i2v",
    "input": {
      "prompt": "一个由喷漆所画成的少年从墙上活过来，演唱英文 rap，夜晚铁路桥下，电影级光影",
      "media": [
        {
          "type": "first_frame",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
        },
        {
          "type": "driving_audio",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 10,
      "prompt_extend": true,
      "watermark": true
    }
  }'
```

<Note>
  `driving_audio` 属于模型能力差异项。`wan2.7-i2v` 支持图片加音频驱动；其他 i2v 模型如不支持音频，请只传 `first_frame`。
</Note>

## 参考图生视频

```bash theme={null}
curl -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-r2v",
    "input": {
      "prompt": "一位身穿这件礼服的女孩在洒满夕阳的花园里缓步行走，微风轻拂裙摆，电影级光影，稳定运镜",
      "media": [
        {
          "type": "reference_image",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "prompt_extend": true,
      "watermark": true
    }
  }'
```

## 视频编辑

```bash theme={null}
curl -X POST "$BASE_URL/wan/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  --data-raw '{
    "model": "wan2.7-videoedit",
    "input": {
      "prompt": "将视频中女孩的衣服替换为图片中的衣服",
      "media": [
        {
          "type": "video",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4"
        },
        {
          "type": "reference_image",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "prompt_extend": true,
      "watermark": true
    }
  }'
```

## 查询和下载

### 查询任务

```bash theme={null}
curl "$BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

完成响应会包含 `status=completed` 和 `result_url`。业务侧建议只依赖顶层字段：

```json theme={null}
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "object": "task",
  "platform": "wan",
  "action": "text_to_video",
  "task_type": "text_to_video",
  "status": "completed",
  "progress": "100%",
  "result_url": "https://dashscope-xxx.oss-accelerate.aliyuncs.com/...",
  "result": {
    "data": {
      "model": "wan2.7-t2v",
      "parameters": {
        "resolution": "720P",
        "duration": 5,
        "prompt_extend": true,
        "watermark": true
      }
    }
  }
}
```

### 下载视频

```bash theme={null}
curl -L -o wan-output.mp4 "$RESULT_URL"
```

<Warning>
  下载 `result_url` 时不要携带 LaoZhang API 的 `Authorization` 头。该地址是上游签名直链，额外的鉴权头可能导致 OSS 返回 403。
</Warning>

## Python 最小客户端

```python theme={null}
import json
import time
import urllib.request
from urllib.error import HTTPError

BASE_URL = "https://api.laozhang.ai"
API_KEY = "YOUR_API_KEY"


def request(method, path, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    if extra_headers:
        headers.update(extra_headers)
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except HTTPError as exc:
        error_body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {error_body}") from exc


created = request(
    "POST",
    "/wan/api/v1/services/aigc/video-generation/video-synthesis",
    {
        "model": "wan2.7-t2v",
        "input": {"prompt": "黄昏海边的灯塔，电影级光影，镜头缓慢推进"},
        "parameters": {"resolution": "720P", "duration": 5, "prompt_extend": True},
    },
    {"X-DashScope-Async": "enable"},
)

task_id = created["output"]["task_id"]

while True:
    task = request("GET", f"/v1/tasks/{task_id}")
    if task["status"] == "completed":
        # result_url 是签名下载地址，不要附加 Authorization 头。
        urllib.request.urlretrieve(task["result_url"], "wan-output.mp4")
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error") or task.get("fail_reason"))
    time.sleep(10)
```

## 常见错误

| 现象                                                          | 常见原因                                                | 处理方式                                |
| ----------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
| `未提供令牌`                                                     | 请求未带 `Authorization`                                | 添加 `Authorization: Bearer $API_KEY` |
| `Current group Wan has no available channels for model ...` | 模型名错误，或当前 `Wan` 分组未配置该模型渠道                          | 检查模型 ID；如模型应可用，联系管理员检查渠道            |
| `[InvalidParameter] Field required: input.media`            | i2v、r2v 或视频编辑任务缺少 `input.media[]`，或误用了 `/v1/videos` | 使用本文的 DashScope 透传端点，并按模型传入对应素材     |
| `任务不存在`                                                     | `task_id` 错误、任务已过期或不是当前站点生成的任务                      | 核对创建响应中的 `task_id`                  |
| 下载 403 或 `SignatureDoesNotMatch`                            | 下载 `result_url` 时携带了额外鉴权头，或签名链接过期                   | 去掉 `Authorization` 头；过期后重新查询任务获取新链接 |

<Tip>
  生产接入建议设置 20 分钟任务超时，保存创建响应、`request_id`、`task_id` 和最终任务详情，方便排查上游错误与扣费记录。
</Tip>