ZenStudio CLI (zencli)

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>

功能一览

| 能力 | 说明 | |------|------| | 🔐 认证管理 | 安全存储 API Key，支持环境变量和交互式输入 | | 📁 项目管理 | 创建、列出、查看、更新项目 | | 🎨 资产库 | 人物 / 道具 / 场景的树形目录管理 | | 🖼️ 媒资管理 | 搜索、创建、查看素材详情 | | ⬆️ 文件上传 | 一键上传图片 / 视频 / 音频到云端 | | ⬇️ 素材下载 | 通过素材 ID 或 URL 下载文件，私有读文件自动签名 | | 🎭 画布管理 | 无限画布项目的创建、编辑和草稿构建 | | 🎯 AI 生图 | 多模型画布生图，支持参考主体图片 | | 🎬 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

AI 生视频

# 查看可用视频模型
zencli generate video-models

# 单图驱动
zencli generate video \
  --mode Text \
  --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 task <task_id>

媒资管理

# 搜索素材
zencli asset search <project_id>

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

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

# 查看素材详情
zencli asset get <asset_id1> <asset_id2>

资产库管理

# 列出人物角色
zencli material list role_person

# 列出道具
zencli material list role_prop

# 列出场景
zencli material list role_scene

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

# 添加素材到资产库
zencli material add --file items.json

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

画布管理

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

# 列出画布
zencli canvas list

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

# 构建草稿（添加素材节点到画布）
zencli canvas build-draft <canvas_id> --file nodes.json

# 删除画布
zencli canvas delete <canvas_id>

素材下载

# 通过素材 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_NO_UPDATE_CHECK | 设为 1 禁用自动版本检查 | — |

配置文件

CLI 配置存储在 ~/.zencli/config.json，包括认证信息和个性化设置。

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

# 列出所有配置项
zencli config list

脚本集成示例

在自动化脚本中使用 zencli：

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

# 获取可用模型列表
MODELS=$(zencli generate image-models -o json)

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

License

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