A full-process command-line tool for AIGC comic-drama video creation for AI Agents, encapsulating 30+ core capabilities of the WorkRally platform, supporting complete CRUD for projects/series/shots, AI image/video generation, canvas, asset library, media asset management, file upload, etc.
Installation & Configuration
npm install -g workrally
# 配置登录。Agent / CI 只用 API Key，不要自己实现 OAuth，也不要请求 127.0.0.1 回调。
workrally auth login --token <YOUR_API_KEY> # Agent / CI
export WORKRALLY_API_KEY=<YOUR_API_KEY> # 环境变量优先于配置文件
workrally auth login # 仅人在本机终端使用，CLI 自己打开浏览器
# ↑ auth login 自动将 Token 写入配置文件：
# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json
# 否则 → ~/.workrally/config.json
workrally auth status # 验证登录状态
API Key application:Lobster configuration
Command quick reference
# === 项目（project）— list / get / create / update / delete ===
workrally project list [--search "关键词"] # 列出/搜索项目
workrally project get <id> # 项目详情
workrally project create "项目名" # 创建项目
workrally project update <id> --name "新名称" # 更新项目
workrally project delete <ids...> # 软删除（→回收站；恢复请到 Web）
# === 剧集（series）— 全新命令组（CRUD 完整） ===
workrally series list --project-id <id> # 剧集列表
workrally series get <series_id> --project-id <id> # 剧集详情
workrally series create --project-id <id> --name "第一集" # 创建剧集
workrally series update <series_id> --project-id <id> --name "新名称" # 更新剧集
workrally series delete <ids...> # 软删除（→回收站）
# === 场次（shotlist）— 对齐 Web /shot 批量制作（含音频生成）===
# --- CRUD ---
workrally shotlist list --series-id <id> # 场次列表
workrally shotlist get <story_id> # 场次详情
workrally shotlist create --series-id <id> --json-list '[{"image_prompt":"..."}]' # 批量创建
workrally shotlist update <story_id> --image-prompt "..." --animation-prompt "..." # 单条更新
workrally shotlist update --batch '[{"story_id":"...","image_prompt":"..."}]' # 批量更新
workrally shotlist delete <story_ids...> # 软删除（→回收站）
workrally shotlist sort --series-id <id> --order id1,id2,id3 # 重排
# --- 模型 & 配置（写入 extra.gen_config）---
workrally shotlist models --category image,video,videoSmartEdit,upscale,audio # ⭐ 统一模型列表
workrally shotlist set-model [--story-ids id1,id2] --image-model <id> --image-aspect-ratio 16:9 [--image-quality high] [--mj-params '{}']
workrally shotlist set-model [--story-ids id1,id2] --video-mode SubjectToVideo --video-model <id> --duration 5 --video-aspect-ratio 16:9
workrally shotlist set-model [--story-ids id1,id2] --extra-mode extendVideo --extend-source-id <asset_id> --duration 4 # 延长视频
workrally shotlist set-model [--story-ids id1,id2] --audio-model <id> [--audio-config '{}'] # 配置音频
workrally shotlist bind --story-id <id> --type audio --file ./voice.wav --project-id <id> # 本地素材：上传→入库→绑定
workrally shotlist bind --story-id <id> --type image --assets '[{...}]' # 已入库素材绑定（audio→独立字段）
workrally shotlist recognize --series-id <id> --project-id <id> [--scope both] [--match-rule symbol_text] # 识别（含音频路）
# --- 生成（仅提交；查结果用 get-result [--watch]）---
workrally shotlist generate-image --project-id <id> --story-ids id1,id2 [--count N] # 生图 → get-result --type image
workrally shotlist generate-video --project-id <id> --story-ids id1,id2 # 生视频 → get-result --type video
workrally shotlist upscale-video --project-id <id> --story-ids id1,id2 --model <id> # 已选视频超分
workrally shotlist generate-audio --project-id <id> --story-ids id1,id2 [--count N] # ⭐ 生音频 → get-result --type audio
workrally shotlist get-result --story-id <id> --type image|video|audio [--watch] # 查进度与产物
# === 上传 / 下载 ===
workrally upload ./file.png -o json # 上传文件 (COS SDK 直传)
workrally download <asset_id> [-d ./output/] # 下载素材 (自动处理访问凭证)
# === AI 生图 ===
workrally generate image-models # 查看可用模型（必须先调用！）
workrally generate image --prompt "描述" --model <model_id> [--aspect-ratio 16:9] [--resolution 5] [--quality high] [--input-images "url"] --poll
# --resolution 推荐用 image-models 的 resolution_options[].value（常见 4=1080P/5=1440P/6=2160P）；旧档位 0/1/2 仍可用
# --quality 仅当 image-models 该模型返回了 infer_quality_options 时才传（取值用其中的 value）
# --extra-params '{"midjourney":{"stylize":100}}' 扩展参数 JSON 对象；CLI 传 extraParams，服务端写成 extra_params
# === AI 生视频 (6 种驱动模式) ===
workrally generate video-models # 查看可用模型（必须先调用！）
workrally generate video --prompt "描述" --model <provider_id> --poll # 纯文生视频（默认 Text 模式）
workrally generate video --prompt "描述" --model <provider_id> --single-image-url "url" --poll # 图生视频（Text 模式 + 参考图）
workrally generate video --mode FirstLastFrame --prompt "描述" --model <provider_id> --first-frame-url "url" --poll # 首尾帧
workrally generate video --mode VideoEdit --prompt "描述" --model <id> --origin-video <asset_id> --poll # 视频编辑
# 其他模式: SubjectToVideo(--reference-assets)
workrally generate video --mode SmartEdit --model <id> --source-video <asset_id> --source-width 1920 --source-height 1080 --source-duration 5000 --poll
workrally generate video --mode ExtendVideo --model <id> --source-video <asset_id> --duration 8 --poll
# SubjectToVideo 的 --reference-assets 支持 file 文档（Wan 3.0）：{"type":"file","asset_id":"...","name":"brief.pdf"}
# --mode 默认 Text；通用选项: --aspect-ratio <比例> --resolution <枚举> --duration <秒> --count 1-4 --poll
# 音效默认开启（与前端一致）；关闭用 --no-enable-sound。VideoEdit 不要传音效相关参数
# --aspect-ratio 默认 16:9；--resolution 不传取模型首个可用(枚举见 video-models 的 resolution_options)
# === 画布生音频 / 音乐（对齐 Web 画布音频生成器）===
workrally generate audio-models # 查看 audio_models / music_models（必须先调用！）
workrally generate audio --prompt "雨声和脚步" --model <id> --poll
workrally generate music --prompt "摇滚吉他" --model <id> --lyrics-mode none --poll
workrally generate music --prompt "流行" --model <id> --lyrics-mode input --lyrics "啦啦啦" --poll
# MiniMax 音频模型不要传 --ref-audios；动态音色参数从模型 fields 获取后用 --audio-fields JSON 传入
# === 混元 3D 模型（对齐 Web 关键帧混元3D，不是世界生成/贴图）===
workrally generate 3d --asset-id <参考图asset_id> --poll
# 须先 asset search / asset create 得到 asset_id；模型固定 hunyuan-3d-v3.0
# ⚠️ --project-id 是短番项目ID，不是画布ID
# === 视频提示词优化（gen_content，产物是文本不是视频）===
workrally generate content-models # 查看可用模型（必须先调用！严禁硬编码 MiniMax H3 等 ID）
workrally generate optimize-prompt --prompt "将视频从尾帧延长5秒" --model <model_id> \
[--video-url <url>] [--first-frame-url <url>] [--last-frame-url <url>] \
[--reference-image-urls "url1,url2"] [--audio-url <url>] [--audio-urls "a.mp3,b.mp3"] --poll
# 图片语义写在 image_info.type：first_frame / last_frame / reference_image；音频写在 audio_info.url（type=3）
# 成功后从 generate task 的 output_text 读取优化后的提示词（output_type="text"），不要找 output_assets
# === 媒资库 (asset) — 项目级媒体文件池 ===
workrally asset create --url <cdn_url> --project-id <id> -o json # 入库（返回可访问 URL）
workrally asset search --project-id <id> [--type image] [--audit-status 5] [--auth-status 1]
workrally asset get <asset_id> # 详情
workrally asset update <asset_id> --name "新名称" # 更新素材 (目前仅支持改名)
# === 资产库 (material) — 树形管理：人物/道具/场景/网盘 ===
workrally material list role_person # 人物 | role_prop 道具 | role_scene 场景 | root 网盘文件夹
workrally material add ... # 创建素材/文件夹（从媒资库挂载）
workrally material get <material_id> # 素材详情
workrally material delete <material_id> # 删除（不可恢复，须用户确认）
workrally role get <role_id> # 角色详情（LoRA/提示词/版本）
# === 画布 ===
workrally canvas list # 列出画布
workrally canvas create "名称" # 创建画布
workrally canvas build-draft <canvas_id> --file nodes.json # 增量合并（默认保留已有节点）
workrally canvas build-draft <canvas_id> --nodes '[...]' # 同上，直接传 JSON
workrally canvas build-draft <canvas_id> -d "id1,id2" # 删除指定节点
workrally canvas build-draft <canvas_id> -n '[...]' -d "old1" # 同时增删改
workrally canvas build-draft <canvas_id> -n '[...]' --mode overwrite # 全量覆盖（清空后重建）
# === 任务查询 ===
workrally generate task <task_id> [--poll] # 查询/轮询生成任务状态
# 生图/生视频成功：output_type="assets"，产物在 output_assets
# 提示词优化成功：output_type="text"，产物在 output_text（不要找 output_assets / output_products）
# === 通用（仅查看白名单，禁止透传调用）===
workrally tools list # 列出核心白名单工具
workrally tools describe <tool_name> # 查看参数 schema
# 不要使用 tools call；未列出的 MCP 工具已禁止调用。关键帧/配音/动效请用 Web。
# === URL / 升级 ===
workrally url build "页面名" [--params '{}'] # 构建 WorkRally 前端链接
workrally url parse <url> # 解析 URL
workrally upgrade [--check] # 升级 / 仅检查
Output format: -o json(default, recommended for Agents) | -o table(human-readable) | -o text(pipe/script) | workrally config set output_format <fmt>
Key workflow: upload files
Concepts: media asset library (asset) = project-level file pool; asset library (material) = tree-structured directory (characters/props/scenes/cloud drive folders). Materials in the asset library can only be mounted from the media asset library.
# 步骤 1: 上传 → CDN URL
workrally upload ./character.png -o json
# 步骤 2: 入媒资库（必须！返回 asset_id + asset_details）
workrally asset create --url <cdn_url> --project-id <project_id> -o json
# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）
workrally material add --json-list '[{"material_id":"<asset_id>","material_name":"名称","material_type":2,"parent_id":"<target_id>","material_detail":<asset_details_json>}]' \
--project-ids <project_id>
Steps 1→2 are mandatory binding, after upload they must be added to the media asset library. Video/audio are private-read and can only be accessed normally through the media asset library.
Step 3 is determined by the Agent: "upload files" → two steps | "upload to character/prop/scene/folder" → three steps | "add media asset material to asset library" → step 3 only
Key workflow: shot creation (shotlist, aligned with Web /shot)
Concept hierarchy: project (project) → series (series) → shot (shot/story). A shot contains image / video / audio three generation lines, with the core carried by prompts:image_prompt(image),animation_prompt(video),extra.audio_prompt(audio, voice tone referenced with <音色名> ). Generation configuration is aggregated in extra.gen_config.{image,video,audio}。
# 1) 建剧集 + 批量创建场次（按用户意图填提示词）
workrally series create --project-id <pid> --name "第一集" -o json
workrally shotlist create --series-id <sid> --json-list '[{"image_prompt":"古风庭院","animation_prompt":"镜头缓推"}]'
# 2) 识别角色资产（三路：image/animation/audio；音色用 <> 时加 --match-rule symbol_text）
workrally shotlist recognize --series-id <sid> --project-id <pid>
# 3) 选模型 → 写配置（模型 id 来自 shotlist models，勿硬编码）
workrally shotlist models --category image,video,audio -o json
workrally shotlist set-model --series-id <sid> --image-model <id> --image-aspect-ratio 16:9 \
--video-mode SubjectToVideo --video-model <id> --duration 5 --video-aspect-ratio 16:9 --audio-model <id>
# 4) 生成（多场次传 --story-ids id1,id2,id3；均需 --project-id）
workrally shotlist generate-image --project-id <pid> --story-ids <ids>
workrally shotlist generate-video --project-id <pid> --story-ids <ids>
workrally shotlist generate-audio --project-id <pid> --story-ids <ids>
# 5) 查结果（image/video/audio 三条独立进度，分别 watch）
workrally shotlist get-result --story-id <sid> --type image --watch
workrally shotlist get-result --story-id <sid> --type video --watch
workrally shotlist get-result --story-id <sid> --type audio --watch
Confirm configuration before generation: use
shotlist get <id>to check whetherextra.gen_confighas the corresponding model set; if missing, return to step 3. Generation only returns the submission result, not a pollable canvas task_id; always useshotlist get-result。
⚠️ Important rules
- Frontend links must be generated with
workrally url buildGenerate, concatenating URLs yourself is strictly prohibited - Model IDs must be obtained dynamically：
image-models/video-models/audio-models/content-models, guessing or hardcoding is strictly prohibited. For batch shot production useshotlist models; thecapabilities/fields/restrictionsreturned by the audio model should also be used for configuration. Hunyuan 3D is fixed at hunyuan-3d-v3.0, only--asset-id canvas≠project: canvas usescanvas, project usesproject, the two IDs cannot be interchangedbuild-draftreal-time collaboration: after writing, all online users immediately see the changes, incremental merge by default (only changed nodes are sent), supporting safe concurrent operations by multiple usersbuild-draftnode validation: the 8 node types each have required fields, seecanvas-guide.md- AI generation automatic placeholder：
generate image/videopass in--project-id(canvas ID) to automatically create a placeholder node on the canvas,no needto manuallybuild-draft - Material naming：
--namepass in "canvas name_material feature" (canvas scene) or prompt keywords (non-canvas scene) - When unsure about parametersuse
--helportools describeExplore on your own - URL whitelist: All URL-type parameters (for image generation/video generation
--*-url/--*-assets/--*-images、asset create --url, etc.) only accept WorkRally official media asset URLs. Valid sources: ①workrally uploadreturn value ②asset get/searchreturn value (can be passed in directly) ③ an official URL already provided by the user. Local files or third-party URLs must first beworkrally upload. If you encounter an "invalid or expired" prompt, simply re-obtain it viaasset get/search.
📚 In-depth Guide (references/)
This Skill comes with detailed reference documentation covering complex workflows:
| Document | Content |
|---|---|
references/shotlist-guide.md |
⭐ Batch scene production(aligned with Web /shot) — CRUD, gen_config, image generation/video generation/audio generation, result querying, symbol recognition |
references/canvas-guide.md |
Infinite canvas operations — 8 node types, artboard nesting, build-draft incremental/overwrite modes, collaborative editing |
references/upload-and-assets-guide.md |
Upload and asset management — three-step upload process, media asset library vs asset library, tree-structured directory operations |
references/ai-generation-guide.md |
AI generation — Kontext image generation, 4 video-driven modes, canvas audio/music, Hunyuan 3D models, prompt optimization, dynamic model retrieval, task polling |
references/common-pitfalls.md |
Common pitfalls — typical mistakes such as project/canvas confusion, hardcoded models, missing upload steps, etc. |
When encountering complex operations related to canvas, upload, or AI generation, please consult the corresponding reference documentation first.
Environment Variables
WORKRALLY_API_KEY— API Key (Bearer Token). Once set, takes precedence over the OAuth login state saved byauth loginSaved OAuth login stateWORKRALLY_ENDPOINT— API endpoint (defaulthttps://workrally.qq.com/zenstudio/api/mcp)WORKRALLY_CONFIG_DIR— configuration file directory (default~/.workrally, for non-persistent containers it is recommended to point to a persistent volume)WORKRALLY_NO_UPDATE_CHECK=1— disable automatic version checking (recommended for CI/CD)