Wan 3.0 视频 API 接入实战：30 秒单镜、全能参考与按秒成本估算（$0.045/秒起）

说明：本文在 AI 辅助下生成。参数、价格和代码来自作者所在平台的接入文档与服务端源码，耗时数据来自我们自己的受控测试，核对日期 2026-10-25。

做商品短片、课程片头或剧情类内容时，最常见的麻烦是镜头太短：很多视频模型单条只能出 5 到 10 秒，想要一段 20 秒以上的连贯画面就得多段拼接，人物和道具在接缝处很容易对不上。

Wan 3.0（万相 3.0）是阿里通义推出的全能视频生成模型：一个模型名同时覆盖文生视频、首帧和首尾帧图生视频、多素材「全能参考」以及文档生视频，原生单镜最长 30 秒、30fps，自带同步音轨。本文用 Python 和 curl 演示四种用法、提示词里怎么指代素材、轮询和回调怎么选，以及一批视频的费用怎么在提交前算清楚。

先说利益关系：下文的接口来自我们自己运营的 apimodels.app，示例代码取自它的 Wan 3.0 接入文档。

准备工作

• Python 3.9 以上，安装 requests；或者直接用 curl。
• 一个 API key，下文用 YOUR_API_KEY 占位。
• 创建任务和查询结果是同一个端点：https://api.apimodels.app/v1/video/generations，POST 创建，GET 带 task_id 查询。

第一步：跑通一条文生视频

视频生成是异步的：创建接口立刻返回 data.taskId，视频在后台生成，之后拿这个 ID 去查结果。

curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-3.0-video",
    "prompt": "A paper airplane gliding over a calm lake at sunrise, camera drifting alongside",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5
  }'

用 Python 创建并轮询，data.state 依次是 pending、processing，最后是 completed 或 failed：

import requests, time

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://api.apimodels.app/v1/video/generations"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

res = requests.post(ENDPOINT, headers=HEADERS, json={
    "model": "wan-3.0-video",
    "prompt": "A paper airplane gliding over a calm lake at sunrise",
    "resolution": "720P",   # 480P / 720P / 1080P
    "ratio": "16:9",        # adaptive(默认)/ 16:9 / 4:3 / 1:1 / 3:4 / 9:16
    "duration": 5,          # 2-30 秒;-1 表示让模型自己决定时长
})
task_id = res.json()["data"]["taskId"]

while True:
    data = requests.get(f"{ENDPOINT}?task_id={task_id}", headers=HEADERS).json()["data"]
    if data["state"] == "completed":
        print("video:", data["resultUrls"][0])
        break
    if data["state"] == "failed":
        print("failed:", data["failMsg"])
        break
    time.sleep(10)

几个参数值得单独说：

• resolution 一定要显式传。 这个接口省略时默认 720P；阿里官方接口省略时默认 1080P，单价是 720P 的两倍。代码迁移时如果漏了这个字段，费用会差一倍。
• audio 默认 true，输出带音轨；关掉不降价。
• prompt_extend 默认 true，会自动改写提示词。短提示词效果提升明显，但会多花时间；已经写好详细提示词时可以关掉。
• seed 取 0 到 2147483647，同样的参数和种子可以复现结果。

四种用法，以及一条互斥规则

同一个模型名，按传入的素材决定用法：

• 文生视频：只传 prompt。
• 首帧 / 首尾帧：first_frame_url，可再加 last_frame_url，图片严格作为第一帧和最后一帧。
• 全能参考：reference_image_urls（最多 10 张）、reference_video_urls（最多 5 段，合计不超过 15 秒）、reference_audio_urls（最多 5 段，合计不超过 15 秒）。
• 文档 / 网页生视频：file_url 传 PPTX、DOCX、XLSX、PDF、TXT、MD 等文档（50 页、100MB 以内），或 link_url 传一个无需登录的公开网页，两者二选一。

文档生视频的请求最简单，把文件地址交给模型，画幅用默认的 adaptive，由模型按素材内容自己挑：

curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-3.0-video",
    "prompt": "A polished product launch film based on this deck",
    "file_url": "https://example.com/launch-deck.pptx",
    "resolution": "1080P",
    "duration": 10
  }'

这种用法适合把产品发布会的幻灯片、活动方案直接变成一条预告片，省掉先写分镜脚本的步骤。文档本身不额外收费，只按输出秒数计。

首尾帧和参考类素材不能混用。混用时上游会判失败，这个接口在创建阶段就直接拒绝，返回的错误会写明冲突的两组字段：

first_frame / last_frame cannot be combined with reference_image_urls / reference_video_urls / reference_audio_urls / file_url / link_url — pick one input mode

提示词：用「图1」「视频1」指代素材

全能参考模式下，提示词按顺序指代素材，图、视频、音频各自独立编号。多个角色、道具和场景要在一条镜头里保持一致，靠的就是这种写法。下面是一个示例请求：

# 示例:人物来自参考视频,道具来自参考图
payload = {
    "model": "wan-3.0-video",
    "prompt": "视频1 里的人拿起 图1 的保温杯，走到 图2 的窗边，镜头缓慢推近，最后停在杯身的标志上",
    "reference_video_urls": ["https://example.com/person.mp4"],
    "reference_image_urls": ["https://example.com/cup.png", "https://example.com/window.jpg"],
    "resolution": "720P",
    "duration": 12,
}

参考素材也可以直接传 base64 或 data URL，服务端会先转存成可访问的地址再交给模型。图片支持 JPEG、PNG（不支持透明通道）、BMP、WEBP，单边 240 到 8000 像素，单张不超过 20MB。

写长镜头时，建议按时间顺序描述画面和镜头运动：30 秒是一条连续镜头，不是几段拼接，提示词写成「先……然后……最后……」比堆砌形容词更容易得到连贯的结果。公开的《Wan3.0 视频创作者手册》收录了 60 多条带成片的提示词案例，覆盖文生、参考、文档生视频、编辑和延长，可以照着它的结构改写自己的提示词。

轮询还是回调

标准档出片以分钟计。我们用同一条提示词、同样参数（480P、9:16、5 秒、关音轨）背靠背测过两次：标准档 356 秒返回，mode: "prime" 高速档 58 秒返回。官方口径是两档能力一致，差别只在速度和单价。轮询建议 10 到 15 秒一次。

批量任务更适合用回调：创建时传 callback_url，任务结束后服务端主动 POST 通知，投递失败会重试，最多投递 3 次。回调地址必须公网可达，填内网或本机地址会在创建时被拒绝。注意结果地址在 data.resultJson 这个 JSON 字符串里，要先解析：

# 示例:Flask 接收回调
from flask import Flask, request
import json

app = Flask(__name__)

@app.post("/wan-callback")
def wan_callback():
    data = request.get_json()["data"]
    if data["state"] == "completed":
        urls = json.loads(data["resultJson"])["resultUrls"]
        print(data["taskId"], urls[0], "billed", data["credits"])
    else:
        print(data["taskId"], "failed:", data["failMsg"])
    return "ok"

回调里的 credits 是这一单的最终实扣金额（美元），失败为 0。事后对账也可以用任务 ID 单独查：

curl https://api.apimodels.app/v1/records/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

成片保存 30 天后自动删除，需要长期使用的要及时转存。

一批视频要花多少钱

按秒计费，费用等于单价乘以计费秒数：

标准档 standard   480P $0.045/秒   720P $0.09/秒   1080P $0.18/秒
高速档 prime      480P $0.068/秒   720P $0.14/秒   1080P $0.28/秒

计费秒数怎么算：

• 只传提示词、参考图、参考音频、文档或网页时，按输出秒数计，这些素材本身不收费。
• 传了参考视频（视频编辑、延长、换人）时，按输入视频时长加输出时长计，且两者合计不能超过 30 秒。
• duration: -1 时先按 30 秒冻结额度，出片后按实际秒数结算，差额退回。
• 失败的任务不扣费。

标准档和高速档怎么选：两档的输入能力、30 秒上限和音轨都一样，高速档贵 51% 到 56%，换来约 6 倍的速度。需要用户在线等结果的交互式工具、反复调提示词的阶段用高速档；夜里跑的批量任务用标准档，多等几分钟不多花钱。

举个例子：100 条 720P、每条 10 秒的商品片，标准档是 100 × 10 × 0.09 = 90 美元，高速档是 140 美元。更省的做法是先用 480P、5 秒出草稿挑方向，100 条草稿 22.5 美元，选中的再用 720P 或 1080P 出终版。

apimodels.app 在这里做了什么

apimodels.app 是一个多模型 API 网关：用一个 API key、一个 OpenAI 兼容端点调用图像、视频、语音和语言模型。Wan 3.0 和平台上的 Seedance、Kling、Veo 走同一个视频端点，换模型只改 model 字段。

稳定性方面，以下几点都能在服务端代码里对应到具体实现：

• Wan 3.0 接了两条上游线路，主线路在创建阶段或生成过程中失败，会自动切到另一条重新提交，客户价格不变。
• 输入冲突、分辨率写错这类问题在创建阶段就拦下，不会白等几分钟才失败。
• 成片交付前统一把 MP4 的索引移到文件头，播放器可以边下边播；这一步只重新封装，不转码。
• 超过 50MB 的生成视频会在交付前压缩到 50MB 以内，分辨率和帧率不变，只降码率，方便直接存进有单文件上限的对象存储。

价格方面就是上面那张表：按秒计费，失败不扣费，每一单的实扣都能用任务 ID 查到。

不适合的情况也说清楚：需要原始码率母带的项目，超过 50MB 的成片会被压缩，不适合；已经开通了阿里云官方账号、只用万相一个模型、习惯按人民币结算的团队，直接调官方接口更省事；需要秒级响应的交互场景，标准档要几分钟，高速档也要接近一分钟，都不合适。

常见问题

• 任务一直是 pending 或 processing：标准档几分钟属于正常，用高速档或改用回调。
• failMsg 提示时长超限：带参考视频时，输入视频总长加输出时长不能超过 30 秒。
• 回调收不到：确认 callback_url 公网可达，创建时如果被拒绝，错误里会说明是内网或本机地址。
• 费用比预期高一倍：检查是否漏传 resolution，或者显式传了 1080P。

你在用 Wan 3.0 做长镜头时，提示词按什么结构写效果最好？欢迎在评论区交流。

接入文档：apimodels.app 的 Wan 3.0 视频 API 文档。