Wan 3.0 Video Prime 视频生成 API

通过 APIMaster 异步视频 API 使用 wan3.0-video-prime。当前集成提供 480P / 720P / 1080P、2–30 秒（整数），每个任务一个视频。参数与适配核查：2026-10-26。

接口与认证

操作	方法和 URL
创建	POST https://apimaster.ai/v1/videos
查询	GET https://apimaster.ai/v1/videos/{task_id}
下载	GET https://apimaster.ai/v1/videos/{task_id}/content

在每个请求上使用 Authorization: Bearer YOUR_API_KEY，创建任务时使用 Content-Type: application/json。使用 APIMaster API key，而不是阿里云 key。APIMaster 提供上游异步头；你不需要 X-DashScope-Async。

兼容的创建端点 /videos/generations 返回不同的响应结构；以下示例始终使用 /videos。

当前路由能力

目前此模型接入了两种适配：阿里云原生路由和 GMI 路由。高级字段需要相应路由；提交某个字段并不会选择该路由。在使用路由特定示例前，请确认你的 API key 可以访问哪条路由。

能力	阿里云原生	GMI
文生视频、首帧、首/尾帧、参考图像	已集成	已集成，但媒体字段不同
参考音频	metadata.input.media	audio_url
文档 / 公共网页	原生媒体字段会被转发；不在已完成生成检查覆盖范围内	不支持
参考视频、编辑、续写	在提交前被阻止	不支持
自动时长 -1	被阻止	被阻止
宽高比 21:9	接受	拒绝
显式音频开关	generate_audio / audio	不支持；请省略这些字段
禁用提示词重写 / 固定种子 0	当前序列化不会保留 prompt_extend: false 或 seed: 0；不要依赖它们	显式的 false 和 0 会被保留

在 2026-10-24 的验收检查中，一个原生路由的 5 秒 720P 无声视频已完成、下载并成功解码。其他媒体组合是根据适配器和官方接口定义描述的，而不是作为经过生成测试的组合呈现。路由可用性和价格可能变化；请参阅模型卡片。

完整通用请求参数

将这些字段放在顶层发送。为获得最广泛的兼容性，请使用显式的 duration、resolution 和 aspect_ratio，使用不超过 5,000 个字符的非空提示词，并省略路由特定选项。

字段	类型	必填 / 默认值	APIMaster 行为
model	string	必填	必须恰好为 wan3.0-video-prime
prompt	string	两条路由均必填	必须非空，包括图生视频。GMI 校验 1–5,000 个字符；原生适配器要求非空文本。官方原生限制为 20,000；避免跨路由依赖该更高限制
duration	integer	5	2–30 秒；不允许 -1、小数或自动时长
seconds	string	可选	字符串别名，例如 "5"；同时提供时必须与 duration 一致
resolution	string	720P	480P、720P、1080P；顶层小写值会被规范化。此 APIMaster 默认值与官方原生默认值不同
aspect_ratio	string	16:9	常用值：adaptive、16:9、9:16、1:1、4:3、3:4。21:9 仅在原生路由上
ratio	string	可选	aspect_ratio 的别名；只使用一个字段，不要发送冲突值
size	string	可选	尺寸别名，例如 1280x720；适用路由特定校验。优先使用 resolution 和 aspect_ratio。GMI 要求较短边匹配分辨率档位；原生仅接受其支持的尺寸映射
input_reference	string	可选	首帧图像 URL。为跨路由兼容，使用可公开下载的 HTTP(S) URL；不要与其他首帧输入组合
prompt_extend	boolean	原生为 true；GMI 省略时采用上游默认值	提示词重写。原生目前无法通过 false 可靠禁用它；GMI 会转发显式布尔值
watermark	boolean	官方原生默认 false；GMI 省略时采用上游默认值	水印开关
seed	integer	省略时随机	跨路由固定种子范围：1–2147483647。原生也接受 -1 表示随机；原生 0 在序列化时会被省略。GMI 接受 0–2147483647 并拒绝 -1。固定种子不保证输出完全一致

原生尺寸别名包括 832x480、480x832、1280x720、720x1280、1920x1080 和 1080x1920，用于常见横屏/竖屏情况。一些方形尺寸映射会归约为 1:1；其他映射尺寸仍可能无法通过宽高比校验。不要使用 size 请求任意尺寸。

路由特定参数表

GMI 字段

这些是除通用表之外的顶层字段。GMI 适配器会拒绝未识别字段，包括 metadata、images、image_urls、audio、generate_audio、video_urls 和 reference_video。

字段	类型	必填 / 默认值	行为
negative_prompt	string	可选	最多 500 个字符
first_frame	string	可选	公共 HTTP(S) 图像 URL；input_reference 的替代项
last_frame	string	可选	公共 HTTP(S) 尾帧图像 URL；还需提供首帧
reference_image	string 或 string[]	可选	1–10 个公共 HTTP(S) 参考图像 URL；多张图像时使用数组
audio_url	string	可选	公共 HTTP(S) 参考音频 URL；受上游媒体校验约束

在一次请求中，使用帧控制或参考图像二者之一。原生 metadata.input.media 在 GMI 上不会转换为这些字段。

阿里云原生字段

原生结构化输入应放在 metadata 内。直接在顶层发送官方 input 或 parameters 对象不符合 APIMaster 契约。始终保留必需的顶层 prompt。

字段	类型	必填 / 默认值	行为
generate_audio	boolean	官方原生默认 true	输出是否包含音轨；false 会被保留
audio	boolean	可选	generate_audio 的别名；只提供一个
images	string[]	可选	会转换为 reference_image 媒体条目；它们不是有序的首/尾帧。不要与 input_reference 组合
metadata	object	可选	封装原生 input 和 parameters；不能更改 model
metadata.input	object	可选	原生输入容器
metadata.input.prompt	string	可选	原生提示词覆盖；优先仅使用顶层提示词
metadata.input.media	object[]	可选	原生媒体集合，每一项都包含 type 和 url
metadata.input.media[].type	string	每项必填	first_frame、last_frame、reference_image、reference_audio、file、link；reference_video 当前被拒绝
metadata.input.media[].url	string	每项必填	媒体位置；建议使用公共 HTTP(S) URL。官方 OSS 临时 URL 需要单独有效的上游上传上下文；APIMaster 不提供该上传上下文
metadata.parameters	object	可选	原生参数容器；不得为 null
metadata.parameters.resolution	string	720P	大写 480P、720P、1080P
metadata.parameters.ratio	string	16:9	原生宽高比，包括 adaptive 和 21:9
metadata.parameters.duration	integer	5	2–30；不允许 -1
metadata.parameters.audio	boolean	官方原生默认 true	输出音频开关
metadata.parameters.prompt_extend	boolean	true	对于 file / link 必须保持 true；显式 false 存在上述序列化限制
metadata.parameters.watermark	boolean	官方原生默认 false	水印开关
metadata.parameters.seed	integer	随机	-1 或 0–2147483647；0 存在上述序列化限制

顶层原生选项会覆盖其对应的 metadata 参数。顶层 input_reference 会替换原生媒体数组；当 input_reference 不存在时，images 会追加参考图像条目。使用一种输入风格和一种参数风格，以避免意外覆盖。不要在原生 input 内使用旧版 img_url、first_frame_url、last_frame_url 或 audio_url；适配器会拒绝 Wan 3.0 的这些旧版媒体字段。

媒体约束

以下官方原生媒体规则也解释了上游侧校验；适配器接受 URL 并不证明媒体有效。

媒体	限制 / 集成说明
首帧 / 尾帧	各最多一个；尾帧需要首帧。不要将帧控制与 reference_image 混用
参考图像	最多 10 张；JPEG/JPG、不带透明度的 PNG、BMP 或 WEBP；每边 240–8,000 px，宽高比最多 8:1，每张图像最多 20 MB
参考音频	原生：最多 5 个，WAV/MP3，每个 1–15 秒，合计最多 15 秒，每个文件最多 15 MB。GMI 仅暴露一个 audio_url
文件 / 网页	仅原生：最多一个文件或一个可公开读取的页面；不要组合 file 和 link。官方文件格式：DOCX、DOC、XLSX、XLS、PPTX、PPT、PDF、TXT、KEY、PAGES、NUMBERS、MD；最多 100 MB，适用分页格式有 50 页限制。保持 prompt_extend: true
参考视频	官方可用，但目前被 APIMaster 原生计费校验阻止；未在 GMI 上暴露。不要在此使用官方 API 的视频编辑或扩展示例

官方原生组合媒体上限为 20 项；单项和组合限制仍然适用。图像 Base64 data URL 是官方原生输入格式的一部分，但 GMI URL 校验不接受它们。跨路由优先使用可下载的 HTTP(S) URL。

示例

文生视频，通用字段

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

首帧，通用字段

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

GMI 首 / 尾帧

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

原生首 / 尾帧和无声输出

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}

原生参考图像和音频

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}

将示例媒体 URL 替换为真实的公共文件。路由特定示例需要匹配的路由，并且仍受上游组合检查约束。

响应、轮询和下载

创建操作返回 APIMaster 任务 ID，例如：

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

字段	含义
id / task_id	APIMaster 任务标识符，不是上游任务标识符
status	queued、in_progress、completed、failed
progress	报告的进度；不保证完成
error.code / error.message	适用时的失败详情
metadata.url	完成时返回的已认证内容地址

使用相同的 API key 每 10–20 秒轮询一次，直到达到终态；创建成功仅表示已接受。生成可能需要数分钟。轮询已接受的任务，而不是反复创建付费任务。

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4

及时下载并保存已完成的视频；上游结果 URL 可能过期。重复轮询不会产生另一次生成费用。

计费和常见错误

计费按请求分辨率的秒数计算，路由/账户价格显示在模型卡片上。提交时会预留预估费用。原生完成时使用返回的可计费时长和冻结的提交价格；GMI 遵循预留时长契约。失败任务会释放/退还其生成预留。关闭音频并不意味着更便宜的档位。最终金额请使用使用日志。

错误 / 症状	操作
duration must be an integer from 2 to 30	使用显式整数；-1 未集成
unsupported Wan request field ...	移除 GMI 不支持的字段，或确认可访问匹配的原生路由
unsupported aspect ratio	使用常见宽高比；21:9 需要原生路由
reference video requires an input-duration quote	移除参考视频；此能力当前被阻止
prompt is required / media fetch failure	添加顶层文本；使用可公开下载的有效媒体
prompt_extend: false 或 seed: 0 对原生无效果	当前序列化限制；使用正种子，不要依赖禁用重写

来源：官方模型信息、官方原生 API 参考 和官方使用指南。官方能力并不意味着相同字段在每条 APIMaster 路由上都暴露。