wan-cli

English | 简体中文

在终端或 coding agent 中调用 Wan 创作图片和视频。

wan-cli 支持文生图、图生图、组图、文生视频、图生视频、参考生视频、视频编辑和 Wan 3.0 Omni，并可为脚本和 agent 返回结构化 JSON。

环境要求

• Node.js 22 或更高版本
• Wan AccessKey

安装

npm install --global @l-design/wan-cli

确认安装成功：

wan --version
wan --help

登录

执行交互式登录，选择 Wan 站点，然后按提示粘贴 AccessKey：

wan auth login

AccessKey 输入不会显示在终端中。你可以保存多个账号，并随时切换当前账号：

wan auth status
wan auth list
wan auth list --use 2
wan logout

Wan AccessKey 与 ModelScope API Key 是两种不同的凭据，不能混用。

快速开始

生成图片：

wan text2image \
  --prompt "一只白色小猫在窗边打盹，电影感，柔和光线" \
  --ratio 1:1

参考图片创作：

wan image2image \
  --image ./portrait.png \
  --prompt "改成电影感棚拍人像" \
  --generation-mode reference

生成视频：

wan text2video \
  --prompt "一艘纸船驶过霓虹闪烁的夜晚城市" \
  --ratio 16:9 \
  --duration 5

让本地图片动起来：

wan image2video \
  --image ./cat.png \
  --prompt "让猫抬头看向镜头" \
  --duration 5

使用参考素材：

wan reference2video \
  --assets ./character.png,./motion.mp4 \
  --start 0 \
  --end 5 \
  --prompt "角色在城市街头奔跑"

使用 Wan 3.0 Omni：

wan omni2video \
  --images ./look.png \
  --videos ./shot.mp4 \
  --video-ranges 1:6 \
  --prompt "自然续写 @视频1，并保持 @图片1 的风格"

命令需要使用本地素材时，CLI 会自动上传。

查询和下载结果

生成命令会返回任务 ID。等待任务完成并保存结果：

wan task wait <task-id> --save --save-dir ./wan-results

也可以单独查询任务或查看最近任务：

wan result get <task-id>
wan task list --page-size 10

添加 --output json 可获得机器可读的输出：

wan task wait <task-id> --output json

主要命令

| 命令 | 用途 | | --- | --- | | wan text2image | 根据文字生成图片 | | wan image2image | 使用一张或多张图片进行创作 | | wan sequential_image | 生成一组连续或相关图片 | | wan text2video | 根据文字生成视频 | | wan image2video | 图片生视频或首尾帧生视频 | | wan reference2video | 使用图片、视频或 Wan 角色作为参考生成视频 | | wan videoedit | 编辑已有视频 | | wan omni2video | 混合使用图片、视频、音频、文档或 URL 创作 | | wan task wait | 等待任务完成并按需下载结果 | | wan task list | 查看最近任务 | | wan credits | 查看账号积分 |

执行 wan <command> --help 可查看该命令支持的完整参数。

Coding agent 与 Skills

安装或更新本包时，会把内置的 wan-cli Skill 同步到本机已检测到的 coding agent。 该 Skill 会指导 agent 使用本地文件、结构化输出、任务轮询，并选择合适的 Wan 创作流程。

你也可以查找和安装 Wan 发布的 Skill：

wan skills list --skill-name <name> --output json
wan skills install '<https-zip-url>' --output json

请只安装 wan skills list 原样返回的 HTTPS 地址。

语言

系统语言为中文时，CLI 使用中文；其他情况下默认使用英文。可通过 --lang 或 WAN_LANG 临时覆盖：

wan --lang zh --help
WAN_LANG=en wan auth login

更新

wan update --check
wan update

使用 wan update --target <version> 可安装指定版本。

配置与安全

账号配置保存在 ~/.wan/config.json。不要提交这个文件，也不要在聊天、日志或截图中 暴露完整 AccessKey。如果 AccessKey 可能已经泄露，请立即前往 Wan 账号页面吊销并重新创建。

项目需要显式覆盖配置时，可使用当前目录的 .env 或环境变量：

WAN_SITE=intl
WAN_ACCESS_KEY="wan-sk.<key-id>.<secret>"

配置优先级依次为：命令行参数、环境变量、.env、用户配置。