ToAPIs
    首页ToAPIs
    图片生成GPT Image 2.6、Gemini 图像…视频生成Seedance、Veo、Kling、Sora…聊天与写作GPT-5.6、Claude、DeepSeek…语音与音乐配音、语音合成、播客
    新上线Seedance 2.5
    价格API 文档MCP
    博客竞品替代
    登录免费试用
    全部模型价格API 文档MCP博客竞品替代
    登录免费试用

    语言

    Esc
    • Seedance 2.5视频生成
    • GPT Image 2图片生成
    • GPT Image 2.6图片生成
    • GPT Image 2.5图片生成
    • Veo 3.1 Fast视频生成
    • Kling 3.0 Turbo视频生成
    • Kling V4 Flash视频生成
    • Grok Video 1.5视频生成
    • Nano Banana 2图片生成
    • Seedream 5.5图片生成
    • FLUX图片生成
    • Sora 2视频生成
    • 全部图片模型用途
    • 全部视频模型用途
    • GPT-5.6 Sol聊天与写作
    • Claude Opus 4.8聊天与编程
    • Claude Opus 4.7聊天与编程
    • DeepSeek V4 ProDeepSeek · 文字
    • Gemini Omni 1.1 FlashGoogle · 多模态
    1. 首页
    2. 博客
    3. 开发教程
    4. 阿里 Wan 3.0 视频 API 入门:下一代视频生成快速上手
    返回全部文章
    tutorial2026-11-208 分钟阅读

    阿里 Wan 3.0 视频 API 入门:下一代视频生成快速上手

    在 ToAPIs 上调用 wan3.0-video 与 wan3.0-video-prime 的生产入门:同一套 All-in-One 接口、首尾帧与参考素材的互斥规则、文件或网页引用、视频编辑约束,以及已文档化的轮询路径。

    ToAPIs Engineering & Evaluation Team
    Wan 3.0Video APITutorialText-to-VideoAlibaba
    TL;DR - 核心要点
    • 已文档化的公共 ID 是 wan3.0-video(标准全能版)和 wan3.0-video-prime。规划稿中的 wan-3-prime 不是当前合同。两个 ID 共用 Wan 3.0 生成参考中的同一套请求结构;没有单独的 Prime 专用端点。
    • 向 POST /v1/videos/generations 提交任务,使用 Bearer API Key。持久化任务 ID 并轮询 GET /v1/videos/generations/{id}。普通任务也可以用 GET /v1/tasks/{id} 查询。官方示例使用 https://toapis.com(中国大陆为 https://toapis.cn)。
    • duration 为 2–30 秒,或 -1 表示智能时长。分辨率为 480p、720p 或 1080p(默认 1080p)。使用 ratio 或 aspect_ratio,不要同时传入。首尾帧模式不能与参考图片、视频、音频、文件或链接混用。
    • 图片、视频、音频、文件和网页必须是公开的 http(s) URL。不要发送 base64 或本地路径。视频编辑要求 ratio=adaptive 且 duration=-1,源视频为 4–30 秒;违反约束会失败并返回 video_edit_parameters_required。
    • 不要沿用未核实的规划稿美元价格。2026-11-20 的型号指南快照中,wan3.0-video 为 26.3 credits / 秒,wan3.0-video-prime 为 41.14 credits / 秒;请以账户目录中的实时报价为准。

    阿里 Wan 3.0 视频 API 入门:下一代视频生成快速上手

    目标型号:wan3.0-video(可选姊妹 ID:wan3.0-video-prime)
    推理接口:https://api.toapis.com/v1/videos/generations
    相关阅读:Wan 3.0 Prime 与 Wan 2.6 Flash 对比 · Kling Video O1 长视频连续性 · Wan 3.0 参考 · wan3.0-video 型号指南 · wan3.0-video-prime 型号指南


    1. TL;DR 与能力概览

    • 先核对目录:规划稿有时写成 wan-3-prime。该字符串不是已文档化的公共 ID。2026-11-20 核对官方 Wan 3.0 生成参考(HTTP 200),列出 wan3.0-video 和 wan3.0-video-prime。两个型号使用该页同一套 All-in-One API。当时不存在单独的 Prime 专用文档路径。
    • 调用约定:异步提交到 POST /v1/videos/generations,再轮询 GET /v1/videos/generations/{id} 直至 completed 或 failed。普通任务也可以用 GET /v1/tasks/{id} 查询。官方示例使用 https://toapis.com(中国大陆为 https://toapis.cn)。本系列其他指南使用 https://api.toapis.com。选定一个源站并保持一致。
    • 同一结构上的多种方式:文生视频;首帧或首尾帧控制;参考图片、视频和音频的联合生成;单个文件或公开网页;以及基于参考片段的视频编辑或延长。首尾帧模式与参考素材模式互斥。
    • 素材:只发送公开的 http:// 或 https:// URL。本地文件请先上传并使用返回的 URL。不要发送 base64 或本地路径。prompt 与媒体素材至少提供一项。
    • 应丢弃的未核实说法:诸如每 5 秒 $0.150 的规划稿单价,不是当前 ToAPIs 文档。请在账户中确认实时价格与渠道支持。

    2. 官方 Wan 3.0 ID、参数与组合规则

    在 model 字段中使用两个公共型号名之一。不要替换成规划稿别名,也不要发明 Prime 模式开关。

    目录 ID在本文中的角色已文档化的能力
    wan3.0-video默认 / 标准全能 ID文生视频、首尾帧、多模态参考、文件或链接、编辑与延长
    wan3.0-video-prime同一结构上的 Prime 姊妹 ID与 wan3.0-video 相同的请求结构;仅在目录中列出且你确实要使用 Prime SKU 时选择它
    wan2.6相关的早期 Wan ID;见 Wan 2.6 生成参考文生视频、图生视频和参考视频,参数映射不同(无 480p;时长为 5/10/15)

    核心请求字段(两个 Wan 3.0 ID 共用):

    字段文档化取值说明
    prompt字符串内容、动作、镜头和声音。prompt 与媒体素材至少提供一项。按数组顺序用“图片1”“视频1”“音频1”引用素材
    duration2–30 的整数,或 -1默认 5。-1 为智能时长——由模型决定长度
    ratioadaptive(默认)、16:9、9:16、1:1、4:3、3:4aspect_ratio 是兼容别名;不要同时传入
    resolution480p、720p、1080p(默认 1080p)本该合同文档化了全部三档
    audio布尔,默认 true默认开启音频
    watermark布尔,默认 false默认关闭
    prompt_extend布尔,默认 true大模型改写可改善短提示词,同时增加耗时;设为 false 则原样使用提示词
    seed可选整数相同参数加种子有助于复现相近结果
    image_with_roles{url, role} 数组role 为 first_frame 或 last_frame。各最多一个;last_frame 必须同时有 first_frame
    reference_images最多 10 个公开图片 URL不能与首尾帧混用
    video_list最多 5 段,总时长 ≤15 秒每项为 {"video_url": "..."}
    audio_with_roles最多 5 段,总时长 ≤15 秒每项为 {url, role: "reference_audio"}
    metadata.media一个 file 或一个 link{type, url}。文件与链接不能同时使用,也不能与首尾帧模式混用
    disable_nsfw布尔,默认 trueToAPIs 平台参数,不会转发给上游。只有显式的 JSON false 才会在账号和销售区域符合条件时启用备用渠道;中国大陆始终禁用

    官方表格中的素材组合规则:

    请求内容是否支持说明
    仅提示词是文生视频
    仅首帧是首帧控制
    首帧和尾帧是尾帧不能单独使用
    参考图片和参考视频是可联合参考,也可再加参考音频
    首帧和参考视频否首尾帧模式与参考素材模式互斥
    文件和网页链接否两者互斥

    如果接口返回类似“Wan 3.0 不能在同一请求中混用首尾帧与参考素材/文件/网页”的信息,请删除其中一类后再提交。

    视频编辑是按提示词分类的路径,不是单独的端点:在提示词中包含编辑意图(例如“edit the video”、“remove”、“replace”),并传入参考片段。这类任务要求 ratio 为 adaptive、duration 为 -1,且输入为 4–30 秒。延长使用“extend”或“continue”等用词,将 duration 设为 -1 或源时长加延长部分(总计 ≤ 30 秒)。

    空白多模态面板穿过六边形网关,汇入单一输出帧

    图 1:已文档化的 Wan 3.0 载荷提交到 POST /v1/videos/generations;轮询同一任务 ID,仅在 status 为 completed 后读取 result.data[0].url。

    若要与 Wan 2.6 Flash 对比能力和成本,见 Wan 3.0 Prime 与 Wan 2.6 Flash。若要在另一产品族上用 3–10 秒窗口做长视频连续性,见 Kling Video O1 指南。


    3. 生产实现:cURL 与 Python

    本系列的国际示例使用 https://api.toapis.com。官方文档要求中国大陆用户使用 https://toapis.cn。每个环境只保留一个源站。

    步骤 1:用 cURL 提交文生视频

    bash
    curl --request POST \
      --url https://api.toapis.com/v1/videos/generations \
      --header "Authorization: Bearer $TOAPIS_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "model": "wan3.0-video",
        "prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
        "duration": 5,
        "ratio": "16:9",
        "resolution": "1080p",
        "audio": true,
        "watermark": false
      }'
    

    首尾帧请求使用 image_with_roles,且不得包含参考素材、文件或链接:

    bash
    curl --request POST \
      --url https://api.toapis.com/v1/videos/generations \
      --header "Authorization: Bearer $TOAPIS_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "model": "wan3.0-video",
        "prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
        "duration": 8,
        "ratio": "adaptive",
        "resolution": "1080p",
        "image_with_roles": [
          {"url": "https://example.com/first-frame.png", "role": "first_frame"},
          {"url": "https://example.com/last-frame.png", "role": "last_frame"}
        ]
      }'
    

    步骤 2:Python 助手与轮询器

    下面的片段遵循已文档化的任务状态路径,以及 queued / in_progress / completed / failed 状态。上线前请对照你账户对应的 API 参考确认 id、result.data[0].url 和响应包络。

    python
    import os
    import time
    import requests
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    ENDPOINT = f"{BASE}/v1/videos/generations"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    DOCUMENTED_IDS = {"wan3.0-video", "wan3.0-video-prime"}
    RATIOS = {"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4"}
    RESOLUTIONS = {"480p", "720p", "1080p"}
    
    
    def dispatch_wan30(
        prompt: str | None = None,
        *,
        model: str = "wan3.0-video",
        duration: int = 5,
        ratio: str = "16:9",
        resolution: str = "1080p",
        audio: bool = True,
        watermark: bool = False,
        prompt_extend: bool | None = None,
        image_with_roles: list[dict] | None = None,
        reference_images: list[str] | None = None,
        video_list: list[dict] | None = None,
        audio_with_roles: list[dict] | None = None,
        media: list[dict] | None = None,
    ) -> str:
        if model not in DOCUMENTED_IDS:
            raise ValueError("Send wan3.0-video or wan3.0-video-prime; wan-3-prime is not a documented public ID")
        if duration != -1 and duration not in range(2, 31):
            raise ValueError("duration must be 2–30 or -1")
        if ratio not in RATIOS:
            raise ValueError("unsupported ratio")
        if resolution not in RESOLUTIONS:
            raise ValueError("resolution must be 480p, 720p, or 1080p")
        roles = [item.get("role") for item in (image_with_roles or [])]
        if "last_frame" in roles and "first_frame" not in roles:
            raise ValueError("last_frame requires first_frame")
        has_frames = bool(image_with_roles)
        has_refs = any([reference_images, video_list, audio_with_roles, media])
        if has_frames and has_refs:
            raise ValueError("first/last-frame mode cannot mix with reference assets, files, or links")
        if media and len(media) > 1:
            raise ValueError("a single request accepts at most one file or one web page")
        if media and len({item.get("type") for item in media}) > 1:
            raise ValueError("file and link cannot be used together")
        if not prompt and not has_frames and not has_refs:
            raise ValueError("provide a prompt or at least one media asset")
        if reference_images and len(reference_images) > 10:
            raise ValueError("reference_images is documented as at most 10")
        if video_list and len(video_list) > 5:
            raise ValueError("video_list is documented as at most 5 clips")
        if audio_with_roles and len(audio_with_roles) > 5:
            raise ValueError("audio_with_roles is documented as at most 5 clips")
        payload: dict = {
            "model": model,
            "duration": duration,
            "ratio": ratio,
            "resolution": resolution,
            "audio": audio,
            "watermark": watermark,
        }
        if prompt:
            payload["prompt"] = prompt
        if prompt_extend is not None:
            payload["prompt_extend"] = prompt_extend
        if image_with_roles:
            payload["image_with_roles"] = image_with_roles
        if reference_images:
            payload["reference_images"] = reference_images
        if video_list:
            payload["video_list"] = video_list
        if audio_with_roles:
            payload["audio_with_roles"] = audio_with_roles
        if media:
            payload["metadata"] = {"media": media}
        res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
        res.raise_for_status()
        data = res.json()
        task_id = data.get("id") or data.get("task_id")
        if not task_id:
            raise RuntimeError(f"Unexpected submission envelope: {data}")
        return task_id
    
    
    def poll_task(task_id: str, deadline_s: int = 900) -> str:
        poll_url = f"{BASE}/v1/videos/generations/{task_id}"
        interval = 10.0
        start = time.time()
        time.sleep(5)
        while time.time() - start < deadline_s:
            poll = requests.get(poll_url, headers=HEADERS, timeout=15)
            if poll.status_code == 429:
                retry_after = poll.headers.get("Retry-After")
                time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
                continue
            poll.raise_for_status()
            data = poll.json()
            status = data.get("status")
            if status == "completed":
                return data["result"]["data"][0]["url"]
            if status == "failed":
                raise RuntimeError(f"Generation failed: {data.get('error')}")
            time.sleep(interval)
            interval = min(interval * 1.5, 30.0)
        raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
    
    
    if __name__ == "__main__":
        task_id = dispatch_wan30(
            "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
            duration=5,
            ratio="16:9",
            resolution="1080p",
        )
        print("Task:", task_id)
        print("Video:", poll_task(task_id))
    

    把提示词模板版本和任务记录放在一起,以便区分参数改动和措辞改动。在 expires_at 之前下载文件;状态参考写明保留窗口为 30 天。若开启 prompt_extend(默认如此),短提示词会额外增加耗时——官方页面只做了定性说明,并未公布实测延迟。


    4. 错误处理与状态矩阵

    下表是诊断起点,并不保证与 ToAPIs 错误码完全一一对应。HTTP 查询成功后仍需读取任务 status。请求错误与 status: failed 的原因(例如 content_policy_rejected、insufficient_user_balance、generation_timeout 或 video_edit_parameters_required)见 错误码参考。

    HTTP 或任务状态常见类别建议操作
    400字段无效、首尾帧与参考素材混用、同时传了 ratio 和 aspect_ratio,或文件与链接并存确认 wan3.0-video 或 wan3.0-video-prime,去掉互斥的一类,并只使用公开 URL
    401缺少或无效的 API Key在 ToAPIs 控制台轮换密钥,并确认 Authorization: Bearer 请求头
    429速率或并发限制如有 Retry-After 请遵守;加抖动退避;仅在安全时重试
    5xx 或客户端超时网关或上游暂时问题先查询已有任务 ID 再决定是否重提
    status: queued 或 in_progress不是错误等待并再次轮询;prompt_extend 可能增加耗时
    status: failed 且原因为 video_edit_parameters_required未满足编辑约束将 ratio 设为 adaptive、duration 设为 -1,并使用 4–30 秒的源视频
    status: failed(其他)生成未成功读取 error.code 与 error.message(若有 error.reason 也一并查看)。不要原样重试被策略拒绝的载荷

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    5. 定价与 FinOps

    Wan 3.0 生成参考并未公布美元或积分价表。2026-11-20 获取的型号指南页面显示,wan3.0-video 的定价参考为 26.3 credits / 秒,wan3.0-video-prime 为 41.14 credits / 秒,并且都写明最终计费以当前账户报价以及当前时长和分辨率规则为准。请把这些积分数字视为快照,而不是对每种分辨率或模式的合同价。不要自行把积分换算成货币,也不要沿用规划稿中的美元单价。

    Estimated cost=successful billable seconds×current account rate for that model and resolution\text{Estimated cost} = \text{successful billable seconds} \times \text{current account rate for that model and resolution}Estimated cost=successful billable seconds×current account rate for that model and resolution

    • 先从中等时长的 wan3.0-video 起步(例如 5 秒),等提示词和素材组合稳定后再提高分辨率或切换到 Prime。
    • 智能时长(-1)和 prompt_extend 会改变模型实际完成的工作量。 它们是已文档化的能力,不能据此假设固定的单次价格或时延。
    • 展示价格不是渠道保证。 在预估批量成本之前,用 GET /v1/models?type=video 和账户目录确认 ID 与实时报价。

    6. 常见问题

    详见 frontmatter 中的 FAQ。摘要:发送 wan3.0-video 或 wan3.0-video-prime,不要发送 wan-3-prime;首尾帧不能与参考素材混用;时长为 2–30 秒或 -1;编辑需要 ratio=adaptive 且 duration=-1;务必轮询 generations 状态路径并持久化任务 ID。


    7. 行动清单

    • 在 ToAPIs 开发者门户 创建密钥。
    • 通过 GET /v1/models?type=video 确认当前密钥能看到 wan3.0-video(若需要,也包括 wan3.0-video-prime)——不要发送 wan-3-prime。
    • 用 duration: 5、ratio: "16:9" 和 resolution: "1080p" 对 cURL 示例做冒烟测试。
    • 以有界超时轮询 GET /v1/videos/generations/{id},并在 expires_at 之前下载结果。
    • 下一步:参阅 Wan 3.0 Prime 与 Wan 2.6 Flash 对比 了解已文档化的能力与成本比较,并查看 wan3.0-video 型号指南 了解实时目录状态。

    本文提到的模型与接口

    UnknownVIDEO

    wan3.0-video

    当前费率:26.3 credits /second
    模型解析页在线试跑获取 API Key
    UnknownVIDEO

    wan3.0-video-prime

    当前费率:41.14 credits /second
    模型解析页在线试跑获取 API Key
    AlibabaVIDEO

    wan2.6

    当前费率:12 credits /second
    模型解析页在线试跑获取 API Key

    相关技术文章

    tutorial2026-11-18T10:00:00+08:008 分钟阅读

    Kling 3.0 Omni API 深挖:多镜头视频生成与物理连贯性

    在 ToAPIs 上调用 kling-v3-omni 的实操指南:官方 Omni 占位符、image_list / video_list / element_list、首尾帧,以及已文档化的轮询路径——不使用未文档化的 shots 数组。

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Omni
    tutorial2026-11-17T10:00:00+08:006 分钟阅读

    上手 Grok-Video-3 API:关于 xAI 视频引擎,你需要先弄清的当前约定

    在 ToAPIs 上调用 xAI Grok Video 的实操指南:当前公共目录列出的是 grok-video-1.0 与 grok-video-1.5,而不是 grok-video-3;本文说明现有 generations 约定、生成模式与轮询路径。

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    comparison2026-11-20T10:00:00+08:008 分钟阅读

    Wan 3.0 Prime 与 Wan 2.6 Flash 对比:生成速度、帧保真度与成本

    在 ToAPIs 上对 wan3.0-video-prime 与 wan2.6-flash 做忠实于合同的对比:已文档化的生成方式、时长与分辨率窗口、官方定价快照,以及为何公开页面不支持给出数值化的时延或节省比例。

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0 Prime
    ToAPIs
    首页ToAPIs
    企业级 AI API 网关,通过统一接口接入 GPT-5、Claude、Gemini 等 200+ 模型。

    热门模型

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    展开更多收起
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • 所有模型

    API 品类

    • AI 图像生成 API
    • AI 视频生成 API
    • 文生视频 API
    • 图生视频 API
    展开更多收起
    • AI 图像编辑 API
    • 语言与推理模型 API
    • 全部 API 工具 →

    替代方案

    替代方案
    • Kie.ai 替代方案
    • Fal.ai 替代方案
    • OpenRouter 替代方案
    • Replicate 替代方案
    • Wavespeed AI 替代方案
    • 全部竞品对比 →

    精选技术指南

    精选技术指南
    • Seedance 2.0 与 2.5 价格对比
    • 低成本 Seedance API 接入指南
    • MiniMax H3 接入指南
    • Seedance 2 免费测试 Key
    • Seedance 2 API 快速开始
    • 全部技术文章 →

    开发者与平台

    开发者与平台
    • API 开发文档
    • MCP
    • 定价
    • 在线模型测试台
    • LLMs.txt
    • 联系支持
    • 模型指南索引
    运营主体:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    注册地址:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    隐私政策服务条款使用政策数据删除政策数据留存政策子处理方与数据区域计费与退款说明Cookie 政策网站地图关于我们

    © 2026 ToAPIs. 版权所有。