跳转到主要内容

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
计费模式按量扣费
HeaderAuthorization: Bearer YOUR_API_KEY
建议为 Wan 视频单独创建令牌,便于按模型、任务和调用日志核对消费
Wan 视频请求必须使用 Wan 分组、按量扣费的令牌。默认分组、Veo 分组、Sora 分组或其他视频分组的令牌可能返回无可用渠道、模型不匹配或计费分组错误。

调用流程

1

创建任务

调用 POST /wan/api/v1/services/aigc/video-generation/video-synthesis。请求体使用 JSON,model 传 Wan 模型 ID,input.prompt 传提示词,图生视频、参考图生视频和视频编辑通过 input.media[] 传素材。
2

轮询状态

调用 GET /v1/tasks/{task_id}。客户端只需要根据顶层 status 字段判断状态,不要解析内部上游字段作为业务状态。
3

下载结果

status=completed 时,读取顶层 result_url 并直接下载。result_url 是上游对象存储签名 URL,下载请求不要携带 LaoZhang API 的 Authorization 头。

API 参考

请求约定

配置项
Base URLhttps://api.laozhang.ai
认证方式Authorization: Bearer YOUR_API_KEY
创建请求格式application/json
创建任务必需 HeaderX-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.messagefail_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-flashWan 2.6 系列与同能力 Wan 2.7 模型一致
happyhorse-1.0-t2v / happyhorse-1.0-i2v / happyhorse-1.0-r2v / happyhorse-1.0-video-editHappyHorse 视频模型与同能力模型一致,具体素材数量按模型能力限制
wan2.7-image-pro 是图片模型,不属于本文的视频生成端点。请不要把它提交到 /wan/api/v1/services/aigc/video-generation/video-synthesis

请求体

顶层字段

字段类型必填说明
modelstring模型 ID,例如 wan2.7-t2v
inputobject输入对象,包含提示词和媒体素材
parametersobject生成参数,例如分辨率、时长、水印

input

字段类型必填说明
promptstring自然语言提示词
mediaarray按模型而定素材数组;t2v 不传,i2v / r2v / videoedit 必填

input.media[]

type用途
first_frame图生视频首帧图片
last_frame尾帧图片,按模型能力使用
reference_image参考图片,可用于 r2v 或视频编辑
driving_audio驱动音频,常用于 wan2.7-i2v
video输入视频,常用于 wan2.7-videoedit
媒体素材 URL 必须是公网可访问的 HTTPS 直链。需要登录、带 Cookie、内网地址或临时不可访问的链接会导致任务失败。

parameters

字段类型推荐值说明
resolutionstring720P可用值通常为 480P720P1080P;建议使用大写 P
durationinteger510视频时长,传整数,不要传字符串
prompt_extendbooleantrue是否启用上游提示词扩写
watermarkbooleantrue是否添加 AI 生成水印
seedinteger可选随机种子,传整数

环境变量

后续示例统一使用以下变量:
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=completedresult_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.mediai2v、r2v 或视频编辑任务缺少 input.media[],或误用了 /v1/videos使用本文的 DashScope 透传端点,并按模型传入对应素材
任务不存在task_id 错误、任务已过期或不是当前站点生成的任务核对创建响应中的 task_id
下载 403 或 SignatureDoesNotMatch下载 result_url 时携带了额外鉴权头,或签名链接过期去掉 Authorization 头;过期后重新查询任务获取新链接
生产接入建议设置 20 分钟任务超时,保存创建响应、request_idtask_id 和最终任务详情,方便排查上游错误与扣费记录。