Wan 3.0 视频生成接口文档

本文档面向通过本平台调用 Wan 3.0 视频生成能力的 API 用户。接口兼容阿里云 DashScope Wan 3.0 的异步 HTTP 调用形式：先创建任务，再轮询任务状态，任务成功后取得视频 URL。

1. 接入信息

1.1 服务地址与认证

• BASE_URL：平台 API 地址，例如 https://api.openfde.work。
• API_KEY：在平台令牌页面创建的 API Key。
• 请求头使用 Authorization: Bearer <API_KEY>。
• 创建任务必须携带 X-DashScope-Async: enable。
• 创建任务的 JSON 请求必须携带 Content-Type: application/json。

这里使用的是平台 API Key，不是阿里云 DashScope API Key。调用阿里云 SDK 时，只有支持自定义 API 地址的 SDK 才能指向本平台。

1.2 模型与接口

项目	值
模型名称	wan3.0-video
创建任务	POST /api/v1/services/aigc/video-generation/video-synthesis
查询任务	GET /api/v1/tasks/{task_id}
调用方式	异步任务

本文档中的完整请求地址均为 BASE_URL + 接口路径。

2. 快速开始

2.1 创建文生视频任务

curl --request POST "$BASE_URL/api/v1/services/aigc/video-generation/video-synthesis" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-DashScope-Async: enable" \
  --data '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "一架纸飞机穿过阳光明亮的图书馆，镜头平稳跟随"
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": true,
      "prompt_extend": true,
      "watermark": false
    }
  }'

创建成功返回 HTTP 200：

{
  "output": {
    "task_id": "06aa0134-fa16-7508-8000-f1005aa80c37",
    "task_status": "PENDING"
  },
  "request_id": "20260908215235185779600nfUPqC6Y"
}

保存 output.task_id，用于后续查询。创建成功仅表示任务已受理，不表示视频已经生成成功。

2.2 查询任务

curl --request GET "$BASE_URL/api/v1/tasks/06aa0134-fa16-7508-8000-f1005aa80c37" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Accept: application/json"

建议每 5 秒查询一次，直到 output.task_status 进入终态。

3. 创建请求参数

请求顶层结构：

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "生成内容描述",
    "media": []
  },
  "parameters": {}
}

3.1 顶层字段

字段	类型	必填	说明
model	string	是	固定为 wan3.0-video
input	object	是	提示词和媒体输入
parameters	object	否	视频生成参数；省略时使用默认值

3.2 input 字段

字段	类型	必填	说明
prompt	string	条件必填	提示词，最长 20000 个字符
media	array	条件必填	结构化媒体输入，详见第 4 节

prompt 与 media 不能同时为空。纯文生视频只传 prompt；使用参考素材时可以同时传入提示词和媒体。

3.3 parameters 字段

字段	类型	必填	默认值	取值与说明
resolution	string	否	1080P	480P、720P、1080P
ratio	string	否	adaptive	adaptive、16:9、4:3、1:1、3:4、9:16
duration	integer	否	5	2 至 30 秒，或 -1 表示智能时长
audio	boolean	否	true	是否生成输出音轨
seed	integer	否	随机	0 至 2147483647；传 -1 也表示随机
prompt_extend	boolean	否	true	是否启用提示词智能改写，详见第 6 节
watermark	boolean	否	false	是否在输出视频中添加水印

reference_audio 表示为模型提供参考音频，audio 表示输出视频是否生成音轨，两者含义不同。需要输出音轨时应设置 audio: true。

4. 媒体输入

每个媒体项均使用以下结构：

{
  "type": "reference_image",
  "url": "https://example.com/reference.png"
}

4.1 支持类型与数量

type	最大数量	用途
first_frame	1	视频首帧
last_frame	1	视频尾帧
reference_image	10	参考图片
reference_video	5	参考视频或视频编辑输入
reference_audio	5	音色、对白、节奏或口型等音频参考
file	1	文档文件参考，例如可下载的 PDF URL
link	1	网页内容参考

4.2 组合规则

• first_frame、last_frame 不能与 reference_image、reference_video、reference_audio、file 或 link 混用。
• file 与 link 不能同时使用。
• reference_image、reference_video 和 reference_audio 可以组合使用。
• file 或 link 可以与普通参考图片、视频或音频组合，但不能与首尾帧组合。
• 参考视频总时长、参考音频总时长等限制可能由模型在异步执行阶段校验，因此任务创建成功后仍可能进入 FAILED。
• 使用视频编辑或延长能力时，输入视频时长与输出时长之和不得超过模型允许的总时长。建议使用 ratio: "adaptive" 和 duration: -1 让输出跟随输入素材。

4.3 URL 与 Base64 规则

• 所有媒体均支持公网可访问的 HTTP(S) URL。带签名 URL 的有效期必须覆盖任务排队和生成时间。
• first_frame、last_frame、reference_image 支持 data:image/...;base64,... 图片数据，解码后单张图片不得超过 20MB。
• 非 link 类型可以使用阿里云官方临时素材地址 oss://dashscope-instant/...。
• 官方兼容入口不接受平台私有的 asset:// 素材引用。
• 网页 URL 中 # 后的片段不会被普通 HTTP 下载请求发送到服务器。对于单页应用，建议优先提供无需片段路由即可直接访问正文的 URL。

调用方应确保素材链接无需登录、无需交互即可下载，并在任务完成前保持有效。

5. 常用请求示例

5.1 首尾帧生视频

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "镜头从首帧自然过渡到尾帧，人物动作连贯",
    "media": [
      {
        "type": "first_frame",
        "url": "https://example.com/first.png"
      },
      {
        "type": "last_frame",
        "url": "https://example.com/last.png"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
    "audio": true
  }
}

5.2 图片、视频和音频多参考

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "保持参考图中的人物外观，参考视频的运镜，并配合参考音频的节奏",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/character.png"
      },
      {
        "type": "reference_video",
        "url": "https://example.com/camera-reference.mp4"
      },
      {
        "type": "reference_audio",
        "url": "https://example.com/audio-reference.mp3"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 8,
    "audio": true,
    "seed": 123456,
    "prompt_extend": true,
    "watermark": false
  }
}

5.3 PDF 文档参考

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "根据文档内容生成一段简洁的介绍视频",
    "media": [
      {
        "type": "file",
        "url": "https://example.com/product-introduction.pdf"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 10,
    "audio": true
  }
}

5.4 网页参考

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "提取网页中的产品特点，生成一段产品介绍视频",
    "media": [
      {
        "type": "link",
        "url": "https://example.com/products/intro"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 10,
    "audio": true
  }
}

6. prompt_extend 说明

prompt_extend 用于控制模型是否对用户提示词进行智能扩写和润色：

• true：允许模型补充场景、动作、镜头语言、光线和画面细节，适合较短或较概括的提示词。
• false：尽量按原始提示词生成，适合提示词已经精确、需要降低自动改写影响的场景。

7. 查询响应与状态

7.1 处理中

{
  "output": {
    "task_id": "06aa0134-fa16-7508-8000-f1005aa80c37",
    "task_status": "RUNNING",
    "submit_time": "2026-09-08 21:52:35.000",
    "scheduled_time": "2026-09-08 21:52:36.000"
  },
  "request_id": "20260908215236737178200gECbwJEq"
}

7.2 生成成功

{
  "output": {
    "task_id": "06aa0134-fa16-7508-8000-f1005aa80c37",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-09-08 21:52:35.000",
    "scheduled_time": "2026-09-08 21:52:36.000",
    "end_time": "2026-09-08 21:54:18.000",
    "video_url": "https://cdn.example.com/video/result.mp4?signature=..."
  },
  "usage": {
    "video_count": 1,
    "duration": 5,
    "output_video_duration": 5,
    "fps": 30,
    "SR": 720,
    "ratio": "16:9"
  },
  "request_id": "20260908215418759355200wnHcaWlY"
}

usage 中部分字段可能因实际执行渠道未返回而省略。调用方不应把缺失字段当作 0。

7.3 任务状态

状态	是否终态	说明
PENDING	否	已受理，等待调度
RUNNING	否	正在生成
SUCCEEDED	是	生成成功，可读取 output.video_url
FAILED	是	生成失败，读取 output.code 和 output.message
CANCELED	是	任务已取消
UNKNOWN	是	任务不存在、已过期、不可见，或不是 Wan 3.0 任务

异步失败仍返回 HTTP 200，错误信息放在 output 中：

{
  "output": {
    "task_id": "06aa0134-fa16-7508-8000-f1005aa80c37",
    "task_status": "FAILED",
    "code": "TaskFailed",
    "message": "task failed"
  },
  "request_id": "20260908215418759355200wnHcaWlY"
}

8. 创建阶段错误

请求格式、鉴权、额度或服务异常使用非 2xx HTTP 状态码，并返回：

{
  "code": "InvalidParameter",
  "message": "parameters.duration must be -1 or between 2 and 30",
  "request_id": "20260908215418759355200wnHcaWlY"
}

HTTP 状态码	code	常见原因
400	InvalidParameter	JSON、模型名、参数范围或媒体组合错误
401	InvalidApiKey	API Key 缺失或无效
403	PermissionDenied	令牌没有模型或分组权限
403	Arrearage	账户额度不足
429	Throttling	请求频率过高或当前容量不足
503	ServiceUnavailable	模型价格或执行服务暂不可用
502/500	InternalError	上游或平台内部异常

程序应同时判断 HTTP 状态码、code 和 request_id，不要依赖 message 文案完全一致。联系技术支持时请提供 request_id 和 task_id，不要提供完整 API Key。

9. 计费与结果 URL

• Wan 3.0 按“分辨率档位每秒单价 × 输出视频时长”计费，具体单价以平台价格页面或管理员配置为准。
• 创建任务时会根据请求的分辨率和时长预留额度；任务成功后按实际输出时长结算，多退少补。
• duration: -1 会按最长 30 秒预留额度，完成后按实际输出时长结算。
• 任务失败时按平台异步任务计费规则退回已预留额度。
• audio 开关不改变计费档位。
• 返回的 video_url 可能包含临时访问签名。请在任务成功后及时下载并转存，不要将其视为永久地址。

10. Python 完整调用示例

以下示例创建任务并轮询到终态。安装依赖：pip install requests。

import os
import time

import requests


BASE_URL = os.environ["BASE_URL"].rstrip("/")
API_KEY = os.environ["API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
}
payload = {
    "model": "wan3.0-video",
    "input": {
        "prompt": "一架纸飞机穿过阳光明亮的图书馆，镜头平稳跟随"
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5,
        "audio": True,
        "prompt_extend": True,
        "watermark": False,
    },
}

create_response = requests.post(
    f"{BASE_URL}/api/v1/services/aigc/video-generation/video-synthesis",
    headers=headers,
    json=payload,
    timeout=30,
)
create_response.raise_for_status()
created = create_response.json()
task_id = created["output"]["task_id"]
print("task_id:", task_id)

query_headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
}
deadline = time.monotonic() + 30 * 60

while True:
    query_response = requests.get(
        f"{BASE_URL}/api/v1/tasks/{task_id}",
        headers=query_headers,
        timeout=30,
    )
    query_response.raise_for_status()
    result = query_response.json()
    output = result["output"]
    status = output["task_status"]
    print("status:", status, "request_id:", result.get("request_id"))

    if status == "SUCCEEDED":
        print("video_url:", output["video_url"])
        print("usage:", result.get("usage"))
        break
    if status in {"FAILED", "CANCELED", "UNKNOWN"}:
        raise RuntimeError(
            f"task ended with {status}: "
            f"{output.get('code', '')} {output.get('message', '')}"
        )
    if time.monotonic() >= deadline:
        raise TimeoutError(f"task {task_id} did not finish within 30 minutes")

    time.sleep(5)

生产环境应为查询请求设置超时和总轮询截止时间，并保存 request_id 以便排查问题。不要把 API Key、完整签名素材 URL 或完整结果 URL写入公开日志。