⌘K

Vtrix CLI Agent 集成

在 Claude Code、Cursor、Codex 等 Agent 环境中集成 Vtrix CLI 的完整指南。

通过 CLI 检索并安装 Skill

Agent 可以直接调用 vtrix skills 命令检索 SkillHub、安装所需技能，无需手动查找文档。

发送这段提示词给你的 Agent，让他来帮你找到需要的 Skill： 
Install this skill https://vtrix.ai/skills/skill.md and follow the instructions to search Skills in vtrix skillhub
1

搜索需要的 Skill

# 关键词搜索
vtrix skills find "video generation"
Search results for "video generation" (3 found)

  seedance_2_0          Seedance V2.0 Video Generation     ★ 4.8  ↓ 12.4k
  seedance_2_0_fast     Seedance V2.0 Fast                 ★ 4.6  ↓ 8.1k
  kirin-video-suite     Kirin Video Suite                  ★ 4.5  ↓ 3.2k
# 按分类浏览，按热度排序
vtrix skills list --category video --sort stars
2

全局安装（自动检测目标 Agent）

vtrix skills add seedance_2_0 -g
Detecting Agent environment...
  ✓ Claude Code detected at ~/.claude/skills/

Installing seedance_2_0 v2.1.0...
  ✓ Downloaded
  ✓ Installed to ~/.claude/skills/seedance_2_0/

Skill ready. Restart Claude Code to activate.
3

Agent 即可通过自然语言调用

重启 Agent 后，Skill 自动加载。Agent 读取 Skill 文件了解参数规格，即可通过自然语言指令直接调用 CLI 提交生成任务。

通过多模态 Skill 生成产物

以 Seedance 2.0（spark_dance_v2_0）为例，展示 Agent 环境中从安装到生成的完整流程。

安装 Skill

vtrix skills add seedance_2_0 -g --yes
✓ Installed seedance_2_0 v2.1.0 → ~/.claude/skills/seedance_2_0/

Agent 调用示例

安装后，Agent（如 Claude Code）可以直接用自然语言触发 Skill，Skill 内部会调用 vtrix run 完成生成：

用户：帮我生成一段 10 秒的城市夜景延时视频，1080p，横屏

Agent（内部执行）：

vtrix run spark_dance_v2_0 \
  --param prompt="cinematic timelapse of city lights at night, cars streaming, urban skyline" \
  --param duration=10 \
  --param resolution=1080p \
  --param ratio=16:9 \
  --output url
Submitting task...
✓ Task created: task_xyz001

Waiting for result...
██████████████████████████  100%  Done

✓ https://cdn.vtrix.ai/outputs/task_xyz001/output.mp4

图像转视频

vtrix run spark_dance_v2_0 \
  --param content='[{"type":"image_url","image_url":"https://example.com/city.jpg"},{"type":"text","text":"time lapse, lights flickering, crowd moving"}]' \
  --param duration=8 \
  --param resolution=1080p \
  --output url
✓ https://cdn.vtrix.ai/outputs/task_xyz002/output.mp4

在脚本 / Agent 工具链中消费结果

# 直接获取 URL 赋值
VIDEO_URL=$(vtrix run spark_dance_v2_0 \
  --param prompt="ocean waves at sunset" \
  --param duration=5 \
  --output url)

# 或获取完整 JSON，用 jq 提取
VIDEO_URL=$(vtrix run spark_dance_v2_0 \
  --param prompt="ocean waves at sunset" \
  --output json | jq -r '.output[0].content[0].url')

echo "Generated: $VIDEO_URL"
异步场景

vtrix run 内部自动轮询直到完成。如需自行控制轮询节奏（如并行提交多个任务），可通过 --output json 拿到 task_id 后用 vtrix task status 手动查询。

响应结构

{
  "id": "task_xyz001",
  "status": "completed",
  "model": "spark_dance_v2_0",
  "output": [{
    "content": [{
      "type": "video",
      "url": "https://cdn.vtrix.ai/outputs/task_xyz001/output.mp4",
      "duration": "10.0"
    }]
  }],
  "usage": { "cost": "0.43334", "quantity": 10 },
  "metadata": { "completed_at": 94.51 }
}