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 视频生成在 LaoZhang API 上的开发接入方式。接口采用 DashScope 兼容异步任务协议:客户端先创建任务并获取 task_id,再轮询任务状态,任务完成后从 result_url 下载 MP4 文件。
Wan 视频生成不使用 Sora / Veo 的 /v1/videos 接口。Wan 2.7 的图生视频、参考图生视频和视频编辑依赖 DashScope 原生 input.media[] 结构,请固定使用本文的 /wan/api/v1/services/aigc/video-generation/video-synthesis 创建任务路径。
认证与令牌
在 令牌管理 创建用于 Wan 视频生成的令牌时,按下面配置:
| 配置项 | 选择 |
|---|
| 控制台入口 | 令牌管理 → 新增令牌 |
| 选择分组 | Wan |
| 计费模式 | 按量扣费 |
| Header | Authorization: Bearer YOUR_API_KEY |
| 建议 | 为 Wan 视频单独创建令牌,便于按模型、任务和调用日志核对消费 |
Wan 视频请求必须使用 Wan 分组、按量扣费的令牌。默认分组、Veo 分组、Sora 分组或其他视频分组的令牌可能返回无可用渠道、模型不匹配或计费分组错误。
调用流程
创建任务
调用 POST /wan/api/v1/services/aigc/video-generation/video-synthesis。请求体使用 JSON,model 传 Wan 模型 ID,input.prompt 传提示词,图生视频、参考图生视频和视频编辑通过 input.media[] 传素材。
轮询状态
调用 GET /v1/tasks/{task_id}。客户端只需要根据顶层 status 字段判断状态,不要解析内部上游字段作为业务状态。
下载结果
当 status=completed 时,读取顶层 result_url 并直接下载。result_url 是上游对象存储签名 URL,下载请求不要携带 LaoZhang API 的 Authorization 头。
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,不要继续轮询 |
Wan / DashScope 的 progress 是粗粒度上报,常见情况是长时间停在 30%,最后直接跳到 100%。只要 status 仍是 in_progress,通常继续等待即可。
模型与输入模式
| 模型 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 视频模型 | 与同能力模型一致,具体素材数量按模型能力限制 |
wan2.7-image-pro 是图片模型,不属于本文的视频生成端点。请不要把它提交到 /wan/api/v1/services/aigc/video-generation/video-synthesis。
请求体
顶层字段
| 字段 | 类型 | 必填 | 说明 |
|---|
model | string | 是 | 模型 ID,例如 wan2.7-t2v |
input | object | 是 | 输入对象,包含提示词和媒体素材 |
parameters | object | 否 | 生成参数,例如分辨率、时长、水印 |
| 字段 | 类型 | 必填 | 说明 |
|---|
prompt | string | 是 | 自然语言提示词 |
media | array | 按模型而定 | 素材数组;t2v 不传,i2v / r2v / videoedit 必填 |
type | 用途 |
|---|
first_frame | 图生视频首帧图片 |
last_frame | 尾帧图片,按模型能力使用 |
reference_image | 参考图片,可用于 r2v 或视频编辑 |
driving_audio | 驱动音频,常用于 wan2.7-i2v |
video | 输入视频,常用于 wan2.7-videoedit |
媒体素材 URL 必须是公网可访问的 HTTPS 直链。需要登录、带 Cookie、内网地址或临时不可访问的链接会导致任务失败。
parameters
| 字段 | 类型 | 推荐值 | 说明 |
|---|
resolution | string | 720P | 可用值通常为 480P、720P、1080P;建议使用大写 P |
duration | integer | 5 或 10 | 视频时长,传整数,不要传字符串 |
prompt_extend | boolean | true | 是否启用上游提示词扩写 |
watermark | boolean | true | 是否添加 AI 生成水印 |
seed | integer | 可选 | 随机种子,传整数 |
环境变量
后续示例统一使用以下变量:
export BASE_URL="https://api.laozhang.ai"
export API_KEY="YOUR_API_KEY"
文生视频
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:
{
"output": {
"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"task_status": "PENDING"
},
"request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
图生视频
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
}
}'
driving_audio 属于模型能力差异项。wan2.7-i2v 支持图片加音频驱动;其他 i2v 模型如不支持音频,请只传 first_frame。
参考图生视频
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
}
}'
视频编辑
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
}
}'
查询和下载
查询任务
curl "$BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $API_KEY"
完成响应会包含 status=completed 和 result_url。业务侧建议只依赖顶层字段:
{
"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
}
}
}
}
下载视频
curl -L -o wan-output.mp4 "$RESULT_URL"
下载 result_url 时不要携带 LaoZhang API 的 Authorization 头。该地址是上游签名直链,额外的鉴权头可能导致 OSS 返回 403。
Python 最小客户端
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 头;过期后重新查询任务获取新链接 |
生产接入建议设置 20 分钟任务超时,保存创建响应、request_id、task_id 和最终任务详情,方便排查上游错误与扣费记录。