ZenStudio CLI (zencli)

⚠️ 品牌升级通知 — ZenStudio CLI → WorkRally

zenstudio-cli (zencli) 已正式升级为 WorkRally。

| 旧 | 新 | |---|---| | npm install -g zenstudio-cli | npm install -g workrally | | 命令 zencli | 命令 workrally | | Skill zenstudio | Skill workrally | | 环境变量 ZENSTUDIO_API_KEY | 环境变量 WORKRALLY_API_KEY | | 配置目录 ~/.zencli | 配置目录 ~/.workrally |

当前 zenstudio-cli 仍可正常使用，但 后续新功能将仅在 workrally 中发布。 建议尽快迁移：npm install -g workrally

ZenStudio 是AI 短番、动画、短剧及影视内容制作全流程工具集，提供 AI 生图、AI 生视频、资产管理、无限画布等一站式 AIGC 创作能力。

zencli 是 ZenStudio 平台的官方命令行工具，让你在终端中即可完成项目管理、素材上传、AI 生成等全部操作，也方便在自动化脚本和 CI/CD 流程中集成 ZenStudio 的能力。

安装

npm install -g zenstudio-cli

要求 Node.js >= 18.0.0。

快速开始

# 1. 登录（API Key 从 ZenStudio 平台获取）
zencli auth login --token <YOUR_API_KEY>

# 2. 查看当前登录用户
zencli whoami

# 3. 列出你的项目
zencli project list

# 4. 上传一张图片
zencli upload ./image.png

# 5. 用 AI 生成图片
zencli generate image-models                    # 查看可用模型
zencli generate image --prompt "一只猫在窗台上" --model <model_id>

# 6. 用 AI 生成视频
zencli generate video-models                    # 查看可用视频模型
zencli generate video --prompt "云海翻涌" --model <provider_id> --poll   # 纯文生视频

功能一览

| 能力 | 说明 | |------|------| | 🔐 认证管理 | 安全存储 API Key，支持环境变量、交互式输入、自定义配置目录 | | 📁 项目管理 | 创建、列出、查看、更新项目 | | 🎨 资产库 | 人物 / 道具 / 场景 / 网盘文件夹的树形目录管理 | | 🖼️ 媒资管理 | 搜索、创建、查看、改名素材 | | ⬆️ 文件上传 | COS SDK 直传图片 / 视频 / 音频到云端 | | ⬇️ 素材下载 | 通过素材 ID 或 URL 下载文件，私有读文件自动签名 | | 🎭 画布管理 | 无限画布项目的创建、编辑、删除和草稿增量构建 | | 🎯 AI 生图 | Kontext 多模型画布生图，支持参考主体图片 | | 🎬 AI 生视频 | 4 种驱动模式（纯文 / 单图 / 首尾帧 / 序列帧 / 参考主体）生视频，支持音效 | | 📊 多格式输出 | JSON / 表格 / 纯文本三种输出模式，方便脚本集成 | | 🔧 通用工具 | 列出、查看、透传调用 MCP 服务端任意工具 | | 🔄 自动升级 | 后台版本检查 + 一键升级，命令不阻塞 |

命令参考

认证与配置

# 登录
zencli auth login --token <YOUR_API_KEY>

# 交互式登录
zencli auth login

# 查看登录状态
zencli auth status

# 登出
zencli auth logout

# 查看当前用户信息
zencli whoami

# 配置管理
zencli config list                  # 列出所有配置
zencli config get output_format     # 查看某项配置
zencli config set output_format table  # 修改配置
zencli config path                  # 查看配置文件路径

项目管理

# 列出所有项目
zencli project list

# 按名称搜索
zencli project list --search "我的动画"

# 分页查询
zencli project list --page 1 --page-size 10

# 创建项目
zencli project create "测试项目"

# 查看项目详情
zencli project get <project_id>

# 更新项目
zencli project update <project_id> --name "新名字"

文件上传

# 上传图片
zencli upload ./character.png

# 上传视频
zencli upload ./demo.mp4

# 静默模式（仅输出 URL，适合脚本管道）
zencli upload ./image.jpg -o text

AI 生图

# 查看可用模型
zencli generate image-models

# 文本生图
zencli generate image \
  --prompt "一只橘猫坐在窗台上，窗外是夕阳" \
  --model <model_id> \
  --aspect-ratio 16:9

# 生成并自动等待结果
zencli generate image \
  --prompt "赛博朋克城市街道" \
  --model <model_id> \
  --poll

# 使用参考图片生成
zencli generate image \
  --prompt "第一张图片在花园中散步" \
  --model <model_id> \
  --input-images "https://example.com/ref.jpg"

# 一次生成多张
zencli generate image \
  --prompt "水墨山水画" \
  --model <model_id> \
  --count 4

# 在画布中生成（自动创建占位节点）
zencli generate image \
  --prompt "古风少女弹琴" \
  --model <model_id> \
  --project-id <canvas_id> \
  --name "我的画布_古风少女弹琴" \
  --poll

AI 生视频

# 查看可用视频模型（必须先调用！）
zencli generate video-models

# 纯文生视频（默认 Text 模式，不传图片）
zencli generate video \
  --prompt "云海翻涌，阳光穿透云层洒向大地" \
  --model <provider_id> \
  --poll

# 图生视频（Text 模式 + 参考图）
zencli generate video \
  --prompt "角色缓缓转头微笑" \
  --model <provider_id> \
  --single-image-url "https://example.com/frame.jpg" \
  --poll

# 首尾帧驱动
zencli generate video \
  --mode FirstLastFrame \
  --prompt "从白天到黄昏的变化" \
  --model <provider_id> \
  --first-frame-url "https://example.com/first.jpg" \
  --last-frame-url "https://example.com/last.jpg"

# 序列帧驱动
zencli generate video \
  --mode FrameSequence \
  --prompt "花朵逐渐绽放" \
  --model <provider_id> \
  --sequence-frames '[{"url":"https://example.com/f1.jpg","timestamp":0},{"url":"https://example.com/f2.jpg","timestamp":2}]'

# 参考主体驱动
zencli generate video \
  --mode SubjectToVideo \
  --prompt "角色在城市街道中奔跑" \
  --model <provider_id> \
  --reference-assets '[{"type":"image","url":"https://example.com/character.jpg"}]'

# 生成音效 + 自定义时长 + 多个
zencli generate video \
  --prompt "海浪拍打沙滩" \
  --model <provider_id> \
  --duration 5 --count 2 --enable-sound --poll

# 在画布中生成（自动创建占位节点）
zencli generate video \
  --prompt "樱花飘落" \
  --model <provider_id> \
  --project-id <canvas_id> \
  --name "我的画布_樱花飘落" \
  --poll

# 查询生成任务状态
zencli generate task <task_id>

# 轮询等待任务完成
zencli generate task <task_id> --poll

💡 --mode 默认 Text，可省略。通用选项：--duration <秒> --count 1-4 --enable-sound --name <名称> --poll

媒资管理

# 搜索素材（project-id 必填）
zencli asset search --project-id <project_id>

# 按关键词搜索
zencli asset search --project-id <project_id> --keyword "角色"

# 按类型筛选
zencli asset search --project-id <project_id> --type video

# 创建素材记录（入库）
zencli asset create --url "https://example.com/image.jpg" --project-id <project_id>

# 画布场景入库（需额外指定 channel 和画布 ID）
zencli asset create --url "https://example.com/image.jpg" \
  --project-id <project_id> \
  --channel toolbox_canvas \
  --canvas-project-id <canvas_id>

# 查看素材详情（支持多个 ID）
zencli asset get <asset_id1> <asset_id2>

# 修改素材名称
zencli asset update <asset_id> --name "新名称"

资产库管理

# 列出人物角色
zencli material list role_person

# 列出道具
zencli material list role_prop

# 列出场景
zencli material list role_scene

# 列出网盘文件夹（用户自建）
zencli material list root

# 按关键词搜索
zencli material list role_person --keyword "战士"

# 查看角色详情（训练状态、LoRA 版本等）
zencli role get <role_id>

# 查看素材详情（支持多个 ID）
zencli material get <material_id1> <material_id2>

# 批量更新素材（重命名/移动/更新描述）
zencli material update --json-list '[{"material_id":"xxx","material_name":"新名称"}]'
# 或从文件读取
zencli material update --file updates.json

# 添加素材到资产库
zencli material add --file items.json --project-ids <project_id>

# 面包屑路径
zencli material breadcrumb <material_id>

画布管理

# 创建画布
zencli canvas create "我的画布"

# 列出画布
zencli canvas list

# 查看画布详情
zencli canvas get <canvas_id>

# 更新画布信息
zencli canvas update <canvas_id> --title "新标题"

# 删除画布（支持多个 ID）
zencli canvas delete <canvas_id1> <canvas_id2>

# 构建草稿 — 增量合并（添加/修改节点，已有节点自动保留）
zencli canvas build-draft <canvas_id> --file nodes.json
zencli canvas build-draft <canvas_id> --nodes '[{"id":"n1","type":"image","position":{"x":0,"y":0},"data":{"asset":{"id":"xxx"}},"style":{"width":400,"height":300}}]'

# 删除指定节点
zencli canvas build-draft <canvas_id> --delete-node-ids "node_id1,node_id2"

# 同时增删改
zencli canvas build-draft <canvas_id> --nodes '[...]' --delete-node-ids "old_id"

# 全量覆盖（清空后重建）
zencli canvas build-draft <canvas_id> --nodes '[...]' --mode overwrite

💡 build-draft 默认增量合并模式，同 ID 覆盖、新 ID 追加、未提及的已有节点保留。 支持的节点类型：image / video / audio / imageGenerator / videoGenerator / artboard / text / freehand。 画布支持多人协同编辑，CLI 写入不会覆盖其他用户的并发操作。

素材下载

# 通过素材 ID 下载
zencli download <asset_id>

# 通过 URL 直接下载
zencli download --url <url>

# 指定输出目录和文件名
zencli download <asset_id> --dir ./output --name my-file.mp4

# 静默模式（不显示进度）
zencli download <asset_id> --quiet

# 输出下载文件路径（适合脚本管道）
zencli download <asset_id> -o text

💡 私有读文件（视频/音频）会自动获取带签名的下载地址，无需手动处理签名。

URL 工具

# 解析 ZenStudio 页面地址
zencli url parse "https://ai.tvi.v.qq.com/zenstudio/project/xxx"

# 构建页面地址
zencli url build "资产库"

# 列出所有可用页面路由
zencli url list

通用工具（高级）

# 列出 MCP 服务端所有可用工具
zencli tools list

# 以 JSON 格式输出
zencli tools list --json

# 查看某个工具的详细参数定义
zencli tools describe <tool_name>

# 透传调用任意工具（键值对参数）
zencli tools call <tool_name> --arg key1=value1 --arg key2=value2

# 透传调用任意工具（JSON 参数）
zencli tools call <tool_name> --json-args '{"key":"value"}'

# 从文件读取参数
zencli tools call <tool_name> --file params.json

💡 tools 命令用于直接与 MCP 服务端工具交互，适合高级用户和调试场景。CLI 内置的命令（如 project、canvas）已覆盖常用功能，优先使用内置命令。

升级

# 检查并自动升级到最新版本
zencli upgrade

# 仅检查是否有新版本
zencli upgrade --check

自动更新提示: zencli 会在每次运行时后台检查新版本 (每 4 小时最多一次, 不阻塞命令执行)。 发现新版时在命令结束后打印提示。设置 ZENCLI_NO_UPDATE_CHECK=1 可禁用。

输出格式

所有命令都支持通过 -o 参数指定输出格式：

# JSON（默认，结构化数据，适合程序解析）
zencli project list -o json

# 表格（适合人类阅读）
zencli project list -o table

# 纯文本（适合管道和脚本）
zencli project list -o text

设置全局默认输出格式：

zencli config set output_format table

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | ZENSTUDIO_API_KEY | API Key（优先于配置文件） | — | | ZENSTUDIO_ENDPOINT | 服务端点地址 | https://ai.tvi.v.qq.com/zenstudio/api/mcp | | ZENCLI_CONFIG_DIR | 配置文件目录（非持久化容器建议指向持久卷） | ~/.zencli | | ZENCLI_NO_UPDATE_CHECK | 设为 1 禁用自动版本检查 | — |

配置文件

CLI 配置存储在 ~/.zencli/config.json（可通过 ZENCLI_CONFIG_DIR 环境变量自定义目录），包括认证信息和个性化设置。

可配置项：endpoint（服务端点 URL）、output_format（json/table/text）、color（是否彩色输出）。

# 查看配置文件位置
zencli config path

# 列出所有配置项
zencli config list

# 设置默认输出格式
zencli config set output_format table

脚本集成示例

在自动化脚本中使用 zencli：

#!/bin/bash
# 确保已设置 API Key
export ZENSTUDIO_API_KEY="your-api-key"

# 批量生成图片并等待结果
zencli generate image \
  --prompt "一个古风少女在竹林中弹琴" \
  --model "$MODEL_ID" \
  --poll \
  -o json

# 纯文生视频 + 轮询等待
zencli generate video \
  --prompt "星空下的极光缓缓流动" \
  --model "$PROVIDER_ID" \
  --duration 5 \
  --poll \
  -o json

# 上传 → 入媒资库 → 下载签名文件
URL=$(zencli upload ./video.mp4 -o text)
ASSET_ID=$(zencli asset create --url "$URL" --project-id "$PROJECT_ID" -o json | jq -r '.id')
zencli download "$ASSET_ID" --dir ./output

License

本项目为专有软件（Proprietary），未经授权不得修改、反编译或重新分发。