SuperAPI AI Directory
Partner中文AI newsFavorites
Skillszenstudio

zenstudio

Design & creation

View repository

Updated 10-15 16:51

About this skill

ZenStudio CLI (zencli)

A command-line tool for the full AI content creation workflow, encapsulating 19+ core capabilities of the ZenStudio platform.

Installation & Configuration

npm install -g zenstudio-cli@1.3.6

# 配置 API Key（三选一）
zencli auth login                          # 交互式登录（推荐）
zencli auth login --token <YOUR_API_KEY>   # 命令行传入
export ZENSTUDIO_API_KEY=<YOUR_API_KEY>    # 环境变量（仅推荐 CI/CD，Agent/子进程可能读不到 shell 配置）
# ↑ auth login 自动将 Token 写入配置文件：
#   若 ZENCLI_CONFIG_DIR 已设置 → $ZENCLI_CONFIG_DIR/config.json
#   否则 → ~/.zencli/config.json

zencli auth status                         # 验证登录状态

API Key Application:Claw Configuration

Command Quick Reference

# === 项目管理 ===
zencli project list [--search "关键词"]    # 列出/搜索项目
zencli project create "项目名"             # 创建项目
zencli project get <id>                    # 项目详情
zencli project update <id> --name "新名称" # 更新项目

# === 上传 / 下载 ===
zencli upload ./file.png -o json           # 上传文件 (COS SDK 直传)
zencli download <asset_id> [-d ./output/]  # 下载素材 (自动处理私有读签名)

# === AI 生图 ===
zencli generate image-models               # 查看可用模型（必须先调用！）
zencli generate image --prompt "描述" --model <model_id> [--aspect-ratio 16:9] [--input-images "url"] --poll

# === AI 生视频 (4 种驱动模式) ===
zencli generate video-models               # 查看可用模型（必须先调用！）
zencli generate video --prompt "描述" --model <provider_id> --poll                        # 纯文生视频（默认 Text 模式）
zencli generate video --prompt "描述" --model <provider_id> --single-image-url "url" --poll  # 图生视频（Text 模式 + 参考图）
zencli generate video --mode FirstLastFrame --prompt "描述" --model <provider_id> --first-frame-url "url" --poll  # 首尾帧
# 其他模式: FrameSequence(--sequence-frames)  SubjectToVideo(--reference-assets)
# --mode 默认 Text；通用选项: --duration <秒> --count 1-4 --enable-sound --poll

# === 媒资库 (asset) — 项目级媒体文件池 ===
zencli asset create --url <cdn_url> --project-id <id> -o json  # 入库（返回带签名 URL）
zencli asset search --project-id <id>      # 搜索
zencli asset get <asset_id>                # 详情
zencli asset update <asset_id> --name "新名称"  # 更新素材 (目前仅支持改名)

# === 资产库 (material) — 树形管理：人物/道具/场景/网盘 ===
zencli material list role_person           # 人物  |  role_prop 道具  |  role_scene 场景  |  root 网盘文件夹
zencli material add ...                    # 创建素材/文件夹（从媒资库挂载）
zencli material get <material_id>          # 素材详情
zencli role get <role_id>                  # 角色详情（LoRA/提示词/版本）

# === 画布 ===
zencli canvas list                         # 列出画布
zencli canvas create "名称"                # 创建画布
zencli canvas build-draft <canvas_id> --file nodes.json          # 增量合并（默认保留已有节点）
zencli canvas build-draft <canvas_id> --nodes '[...]'            # 同上，直接传 JSON
zencli canvas build-draft <canvas_id> -d "id1,id2"               # 删除指定节点
zencli canvas build-draft <canvas_id> -n '[...]' -d "old1"       # 同时增删改
zencli canvas build-draft <canvas_id> -n '[...]' --mode overwrite  # 全量覆盖（清空后重建）

# === 任务查询 ===
zencli generate task <task_id> [--poll]    # 查询/轮询生成任务状态

# === 通用透传（调用任意 MCP 工具）===
zencli tools list                          # 列出所有工具
zencli tools describe <tool_name>          # 查看参数 schema
zencli tools call <tool_name> --arg key=value [--json-args '{}']

# === URL / 升级 ===
zencli url build "页面名" [--params '{}']  # 构建 ZenStudio 前端链接
zencli url parse <url>                     # 解析 URL
zencli upgrade [--check]                   # 升级 / 仅检查

Output format: -o json(default, Agent recommended) | -o table(human-readable) | -o text(pipe/script) | zencli config set output_format <fmt>

Key workflow: uploading files

: Media asset library (asset) = project-level file pool; material library (material) = tree-structured directory (characters/props/scenes/cloud drive folders). Materials in the material library can only be mounted from the media asset library.: Media asset library (asset) = project-level file pool; material library (material) = tree-structured directory (characters/props/scenes/cloud drive folders). Materials in the material library can only be mounted from the media asset library.

# 步骤 1: 上传 → CDN URL
zencli upload ./character.png -o json
# 步骤 2: 入媒资库（必须！返回 asset_id + 带签名的 asset_details）
zencli asset create --url <cdn_url> --project-id <project_id> -o json
# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）
zencli material add --material-id <asset_id> --material-detail '<asset_details_json>' \
  --parent-id <target_id> --type 2 --project-ids <project_id>

, binding after upload is mandatory, after uploading it must be added to the media asset library. Videos/audio are private-read; only URLs after being added to the library carry signatures.

: "Upload file" → two steps | "Upload to character/prop/scene/folder" → three steps | "Add media asset to material library" → step 3 only: "Upload file" → two steps | "Upload to character/prop/scene/folder" → three steps | "Add media asset to material library" → step 3 only

⚠️ Important Rules

  1. Frontend links must be generated with zencli url build Frontend links must be generated with; concatenating URLs by yourself is strictly prohibited
  2. Model IDs must be obtained dynamically：image-models / video-models, guessing or hardcoding is strictly prohibited
  3. canvas ≠ project: For canvas use canvas, for short drama projects use project, do not mix them
  4. build-draft takes effect in real time: Users currently viewing the canvas after writing willimmediatelysee the changes without needing to refresh the page
  5. build-draft defaults to incremental merging: Only pass the changed nodes (added/modified); existing nodes are automatically retained. To delete use -d, for full overwrite use --mode overwrite
  6. build-draft supports multi-user collaboration: When the CLI writes to the canvas it will not overwrite other users' concurrent edits, and you can safely operate on the same canvas simultaneously with browser users
  7. build-draft node data validation：
    • type must be one of image/video/audio/imageGenerator/videoGenerator/artboard/text/freehand must be one of
    • image/video/audio nodemust contain data.asset.id(non-empty string), otherwise it will be rejected
    • text nodemust contain data.text.content(text content, maximum 2000 characters), optional fontSize/fontWeight/textAlign/color
    • freehand nodemust contain data.freehand.points(stroke coordinate array) and data.freehand.initialSize({width,height}), optional color/size
    • audio node default size 260×80;artboard node defaults to 600×800 when size is missing
    • The server will automatically fix common issues (such as empty style, missing measured, text/freehand default attributes), but missing key required fields cannot be fixed
  8. Best practices for material naming：
    • In-canvas generation: Use --name to pass "canvas name_material feature" as the name (e.g. "Product Design Canvas_Blue Sneakers"), via canvas list to get the canvas name
    • Non-canvas generation: Use --name Pass in a custom name to extract core keywords from the prompt
  9. When unsure about parametersUse --help or tools describe to explore on your own

Environment variables

  • ZENSTUDIO_API_KEY — API Key (Bearer Token)
  • ZENSTUDIO_ENDPOINT — API endpoint (default https://ai.tvi.v.qq.com/zenstudio/api/mcp)
  • ZENCLI_CONFIG_DIR — configuration file directory (default ~/.zencli, for non-persistent containers it is recommended to point to a persistent volume)
  • ZENCLI_NO_UPDATE_CHECK=1 — disable automatic version check (recommended for CI/CD)

Tool description

This skill uses the following tools:

  • Read: read project files and configuration