万相 2.7 视频生成

使用 EasyRouter 统一接口调用阿里云万相 2.7 全系列视频生成模型，支持文生视频、图生视频、参考生视频、视频编辑四种能力。

万相 2.7（Wan 2.7）是阿里云百炼推出的新一代视频生成模型家族，支持 1080P 电影级画质、最长 15 秒视频、多镜头叙事与原生音频同步。EasyRouter 将上游 DashScope 的异步任务接口封装为统一的 /v1/video/generations 异步任务接口对外提供服务，覆盖文生视频、图生视频、参考生视频、视频编辑四种能力。

万相 2.7 是异步任务型接口：提交后立即返回 task_id，你需要轮询任务状态，成功后从 data.result_url 下载视频。

一、支持的模型

模型	能力	必传媒体输入	说明
`wan2.7-t2v`	文生视频	—	纯文本描述生成视频，支持多镜头叙事与音频同步
`wan2.7-i2v`	图生视频	1 张首帧图	以首帧图为起点，按 prompt 生成后续动作
`wan2.7-r2v`	参考生视频	1~9 张参考图	多图参考生成，保持角色/物体一致性，prompt 中用 `[Image N]` 指代
`wan2.7-videoedit`	视频编辑	1 段视频 + 0~3 张参考图	按文本指令对视频做风格转换、元素替换、局部修改等

4 个模型统一使用同一个接口路径 /v1/video/generations，仅通过 model 字段区分能力；响应体结构完全一致。

二、通用接口

2.1 提交任务

POST /v1/video/generations

请求头

Header	必填	说明
`Authorization`	✓	`Bearer sk-你的APIKey`
`Content-Type`	✓	`application/json`

请求体字段

字段	类型	必填	说明
`model`	string	✓	万相 2.7 模型名，见上表
`prompt`	string	✓	文本提示词，最长 5000 字符，支持中英文
`resolution`	string	—	分辨率档位，可选 `720P` / `1080P`（默认 `720P`）。推荐使用此字段，与阿里云官方 API 字段名一致
`size`	string	—	兼容旧版字段名。若与 `resolution` 同时传入，`resolution` 优先；若仅传 `size`，则以 `size` 的值作为分辨率。新接入建议改用 `resolution`
`duration`	int	—	视频时长（秒），t2v/i2v 取值 `2~15`，默认 `5`；r2v 含参考视频时取值 `2~10`；`videoedit` 忽略此字段，时长跟随输入视频（最长 15 秒）
`input_reference`	string	见模型	i2v 专用：首帧图公网 URL
`images`	array	见模型	videoedit 专用：媒体 URL 数组，第一个元素为待编辑视频（MP4/MOV），后续元素为参考图（可选，最多 3 张）
`metadata`	object	—	万相 2.7 特有参数容器，见第三节

images 字段目前处于发版过渡期：发版前请使用 metadata.input.media 数组传入媒体素材；发版后系统会自动根据 URL 扩展名推断媒体类型，images 字段即可直接使用。具体以接口实际表现为准。

响应

{
  "id": "task_AbCdEf1234567890XyZw",
  "task_id": "task_AbCdEf1234567890XyZw",
  "object": "video",
  "model": "wan2.7-t2v",
  "status": "queued",
  "progress": 0,
  "created_at": 1778300000
}

id / task_id 是 EasyRouter 生成的公开 ID（task_ 前缀），用于后续查询。不等于上游 DashScope 的 task_id，请务必使用此处返回的值。

2.2 查询任务状态

GET /v1/video/generations/{task_id}

响应采用 EasyRouter 统一的 {code, message, data} 包装格式，data 中包含任务详情、扣费信息、渠道信息及上游原始响应。

响应（排队中 / NOT_START）

{
  "code": "success",
  "message": "",
  "data": {
    "id": 42,
    "task_id": "task_AbCdEf1234567890XyZw",
    "platform": "17",
    "user_id": 3,
    "group": "default",
    "channel_id": 18,
    "quota": 250000,
    "action": "textGenerate",
    "status": "NOT_START",
    "fail_reason": "",
    "submit_time": 1778300000,
    "start_time": 0,
    "finish_time": 0,
    "created_at": 1778300000,
    "updated_at": 1778300000,
    "progress": "0%",
    "properties": {
      "input": "",
      "upstream_model_name": "wan2.7-t2v",
      "origin_model_name": "wan2.7-t2v"
    },
    "data": {
      "output": {
        "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "task_status": "PENDING"
      },
      "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

响应（生成中 / IN_PROGRESS）

{
  "code": "success",
  "message": "",
  "data": {
    "id": 42,
    "task_id": "task_AbCdEf1234567890XyZw",
    "status": "IN_PROGRESS",
    "progress": "40%",
    "submit_time": 1778300000,
    "start_time": 1778300010,
    "finish_time": 0,
    "properties": {
      "upstream_model_name": "wan2.7-t2v",
      "origin_model_name": "wan2.7-t2v"
    },
    "data": {
      "output": { "task_status": "RUNNING" }
    }
  }
}

响应（成功 / SUCCESS）

{
  "code": "success",
  "message": "",
  "data": {
    "id": 42,
    "task_id": "task_AbCdEf1234567890XyZw",
    "platform": "17",
    "user_id": 3,
    "group": "default",
    "channel_id": 18,
    "quota": 250000,
    "action": "textGenerate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/.../output.mp4?Expires=...&Signature=...",
    "submit_time": 1778300000,
    "start_time": 1778300010,
    "finish_time": 1778300095,
    "created_at": 1778300000,
    "updated_at": 1778300095,
    "progress": "100%",
    "properties": {
      "input": "",
      "upstream_model_name": "wan2.7-t2v",
      "origin_model_name": "wan2.7-t2v"
    },
    "data": {
      "output": {
        "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/.../output.mp4"
      },
      "usage": {
        "video_duration": 5,
        "video_ratio": "16:9",
        "video_count": 1
      },
      "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

响应（失败 / FAILURE）

{
  "code": "success",
  "message": "",
  "data": {
    "id": 42,
    "task_id": "task_AbCdEf1234567890XyZw",
    "status": "FAILURE",
    "fail_reason": "DataInspectionFailed: input data may contain inappropriate content",
    "progress": "100%",
    "data": {
      "output": { "task_status": "FAILED" }
    }
  }
}

关键字段

字段	类型	说明
`code`	string	响应码，成功时为 `"success"`
`message`	string	响应消息
`data.id`	int	内部任务自增 ID
`data.task_id`	string	EasyRouter 公开任务 ID（以 `task_` 开头）
`data.status`	string	任务状态：`NOT_START` / `QUEUED` / `IN_PROGRESS` / `SUCCESS` / `FAILURE`
`data.result_url`	string	视频结果 URL（仅 `SUCCESS` 时非空，为上游 OSS 临时签名链接）
`data.fail_reason`	string	失败原因（仅 `FAILURE` 时非空）
`data.quota`	int	本次任务扣费的 quota 原始值
`data.progress`	string	进度字符串，形如 `"40%"` / `"100%"`
`data.submit_time` / `start_time` / `finish_time`	int64	提交 / 开始 / 完成的 Unix 时间戳（秒）
`data.created_at` / `updated_at`	int64	记录创建 / 最近更新时间
`data.properties.upstream_model_name`	string	实际发给上游 DashScope 的模型名
`data.properties.origin_model_name`	string	客户端请求的模型名
`data.data`	object	上游 DashScope 原始响应（含 `output.video_url`、`usage`、`request_id`）

状态枚举

状态	对应 DashScope 状态	说明
`NOT_START`	`PENDING`	已创建，尚未开始处理
`QUEUED`	`PENDING`	已进入上游队列
`IN_PROGRESS`	`RUNNING`	生成中
`SUCCESS`	`SUCCEEDED`	已完成，`result_url` 为视频地址
`FAILURE`	`FAILED` / `CANCELED` / `UNKNOWN`	生成失败，`fail_reason` 为失败原因

视频 URL（data.result_url）是上游 OSS 签名链接，24 小时有效，获取后请尽快下载或转存到你自己的存储。

三、万相 2.7 特有参数（metadata）

以下字段通过请求体的 metadata 对象传递，EasyRouter 会透传给上游 DashScope。

3.1 通用控制参数

字段	类型	适用模型	说明	默认值
`ratio`	string	t2v / r2v	宽高比，可选 `16:9` / `9:16` / `1:1` / `4:3` / `3:4`	`16:9`
`seed`	int	所有	随机种子，取值 `0 ~ 2147483647`，未指定自动生成	—
`negative_prompt`	string	所有	负向提示词，描述不希望出现的内容，最长 500 字符	—

i2v 不支持 ratio 参数：图生视频的宽高比自动跟随输入首帧图的比例。

3.2 多媒体输入（metadata.input.media）

r2v 与 videoedit 如需通过 metadata 传入媒体素材，使用 metadata.input.media 数组：

{
  "metadata": {
    "input": {
      "media": [
        { "type": "reference_image", "url": "https://.../img1.jpg" },
        { "type": "reference_image", "url": "https://.../img2.jpg" },
        { "type": "video", "url": "https://.../video.mp4" }
      ]
    }
  }
}

`type`	用途	数量限制
`reference_image`	参考图片	r2v: 1~~9 张；videoedit: 0~~3 张
`video`	待编辑视频（仅 videoedit 使用）	必须且仅有 1 个
`first_frame`	首帧图（仅 i2v 使用，也可通过顶层 `input_reference` 传递）	仅 1 张

r2v 提示词规范：在 prompt 中通过 [Image 1]、[Image 2] 按数组顺序指代参考图，例如"[Image 1]中身着红色旗袍的女性，轻抬玉手展开[Image 2]中的折扇"。

3.3 媒体素材限制

类型	格式	分辨率	文件大小	其他限制
图片（i2v 首帧）	JPEG / JPG / PNG / WEBP	宽高 240~8000 像素	≤ 10 MB	宽高比 1:8 ~ 8:1
图片（r2v 参考图）	JPEG / JPG / PNG / WEBP	短边 ≥ 300 像素	≤ 10 MB	推荐清晰图，避免模糊过压
图片（videoedit 参考图）	JPEG / JPG / PNG / BMP / WEBP	240~8000 像素	≤ 20 MB	宽高比 1:8 ~ 8:1
视频（videoedit 输入）	MP4 / MOV（推荐 H.264）	宽高 240~4096 像素	≤ 100 MB	时长 2~10 秒，宽高比 1:8 ~ 8:1

四、完整调用示例

# Step 1: 提交任务
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-t2v",
    "prompt": "一只小猫在月光下奔跑，毛发随风轻轻飘动，电影感慢镜头",
    "resolution": "720P",
    "duration": 5,
    "metadata": {
      "ratio": "16:9",
      "seed": 42
    }
  }'

# 返回示例：
# {
#   "id": "task_AbCdEf1234567890XyZw",
#   "task_id": "task_AbCdEf1234567890XyZw",
#   "status": "queued", ...
# }

# Step 2: 轮询（建议间隔 10~15 秒）
curl https://easyrouter.io/v1/video/generations/task_AbCdEf1234567890XyZw \
  -H "Authorization: Bearer sk-你的APIKey"

# Step 3: 当 data.status == "SUCCESS" 后，从 data.result_url 下载视频
curl -o output.mp4 "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/.../output.mp4?Expires=..."

# i2v：通过 input_reference 传入首帧图
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "写实风格，一只小黑猫好奇地仰望天空，镜头缓缓推近",
    "resolution": "720P",
    "duration": 5,
    "input_reference": "https://wanx.alicdn.com/material/20250318/first_frame.png"
  }'

i2v 的宽高比自动跟随 input_reference 输入图像，不支持 metadata.ratio。

# r2v：参考图通过 metadata.input.media 传入，prompt 中用 [Image N] 指代
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-r2v",
    "prompt": "参考图片，3D卡通冒险电影风，角色Q版但材质细腻，[Image 1]中的角色欢快地奔跑",
    "resolution": "720P",
    "duration": 5,
    "metadata": {
      "ratio": "16:9",
      "input": {
        "media": [
          {
            "type": "reference_image",
            "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png"
          }
        ]
      }
    }
  }'

# videoedit：待编辑视频 + 参考图，通过 images 数组传入
# 第一个元素为视频（MP4），后续为参考图（PNG/JPG）
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-videoedit",
    "prompt": "将视频中女孩的衣服替换为图片中的衣服",
    "resolution": "720P",
    "images": [
      "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4",
      "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
    ]
  }'

videoedit 不需要指定 duration，输出时长跟随输入视频（最长 15 秒）。images 数组中第一个 MP4/MOV 链接视为待编辑视频，其余 PNG/JPG/WEBP 链接视为参考图。

五、OpenAI 兼容接口（可选）

除 /v1/video/generations 外，万相 2.7 同时兼容 OpenAI 风格的 /v1/videos 接口。两套接口完全等价，选择哪一个由你的客户端集成方式决定。

5.1 提交（OpenAI 兼容）

POST /v1/videos

请求体字段与 /v1/video/generations 完全一致。

5.2 查询（OpenAI 兼容）

GET /v1/videos/{task_id}

返回 OpenAI 标准扁平格式：

{
  "id": "task_AbCdEf1234567890XyZw",
  "object": "video",
  "model": "wan2.7-t2v",
  "status": "completed",
  "progress": 100,
  "created_at": 1778300000,
  "completed_at": 1778300095,
  "metadata": {
    "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/.../output.mp4?Expires=...&Signature=..."
  }
}

OpenAI 状态	对应统一格式状态
`queued`	`NOT_START` / `QUEUED`
`in_progress`	`IN_PROGRESS`
`completed`	`SUCCESS`
`failed`	`FAILURE`

六、计费说明

万相 2.7 按视频秒数 × 分辨率系数计费：

分辨率	单价	示例（5 秒）
`720P`	$0.10 / 秒	5 × $0.10 = $0.50
`1080P`	$0.15 / 秒	5 × $0.15 = $0.75

quota 换算公式：

quota = modelPrice × QuotaPerUnit × groupRatio × seconds × resolutionRatio

QuotaPerUnit    = 500,000
modelPrice      = 0.10（所有 wan2.7 模型）
groupRatio      = 1.0（生产 default 组）
resolutionRatio = 720P → 1.0，1080P → 1.5

示例：
  720P × 5 秒  = 0.10 × 500,000 × 1 × 5 × 1.0 = 250,000 quota
  1080P × 10 秒 = 0.10 × 500,000 × 1 × 10 × 1.5 = 750,000 quota

任务 FAILURE 时 EasyRouter 会自动退款到你的账户（日志中 type=6），无需手动处理。

七、轮询建议

项	建议
轮询间隔	10~15 秒一次，不要小于 5 秒
终态判断	`data.status == "SUCCESS"` 或 `data.status == "FAILURE"`
总超时时间	t2v / i2v / r2v 建议 5 分钟；videoedit 建议 8~10 分钟
典型耗时	t2v / i2v / r2v：30~~100 秒；videoedit：3~~5 分钟
视频 URL 有效期	24 小时，获取后请立即下载或转存

简易轮询脚本（Bash）

#!/bin/bash
TID="task_AbCdEf1234567890XyZw"
KEY="sk-你的APIKey"
while true; do
  RESP=$(curl -sS "https://easyrouter.io/v1/video/generations/$TID" \
    -H "Authorization: Bearer $KEY")
  echo "$RESP"
  STATUS=$(echo "$RESP" | python3 -c \
    "import sys,json;print(json.load(sys.stdin)['data'].get('status',''))")
  case "$STATUS" in
    SUCCESS|FAILURE) break ;;
  esac
  sleep 15
done

八、错误处理

8.1 HTTP 400 参数错误（提交前拦截，不扣费）

场景	响应
未传 `prompt`	`{"code":"invalid_request","message":"prompt is required","data":null}`
未知模型名	`{"code":"invalid_request","message":"unknown model: ..."}`
`images` 数组为空	`{"code":"invalid_request","message":"images is required for videoedit"}`

8.2 HTTP 401 / 403 鉴权错误

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 无权访问此模型

8.3 HTTP 402 余额不足

返回 insufficient user quota，请前往 EasyRouter 控制台充值。

8.4 任务 FAILURE 状态

常见原因	处理建议
`DataInspectionFailed`	上游安全审核拦截，调整 prompt 或素材；阿里对部分官方示例素材也可能触发此错误，属上游行为
i2v 未提供 `input_reference`	图生视频必须传入首帧图
r2v 参考图数量为 0	至少提供 1 张 `reference_image`
videoedit 未提供视频	`images[0]` 必须是 MP4/MOV 视频链接
媒体 URL 不可访问	确保 URL 公开可访问、未过期
媒体文件不符规格	参考第 3.3 节素材限制