vtrix run

用法

vtrix run <model_id> [--param key=value ...] [--output url|json] [--timeout 600]

命令内部自动轮询，任务完成后将结果输出到 stdout，进度信息输出到 stderr。

# 文本转视频
vtrix run spark_dance_v2_0 \
  --param prompt="neon cityscape timelapse" \
  --param duration=5 \
  --output url

# 图像转视频
vtrix run kirin_v2_6_i2v \
  --param image=https://example.com/cat.jpg \
  --output url

# 演练模式（全局 flag，不发请求，无需登录）
vtrix --dry-run run spark_dance_v2_0 --param prompt="neon city"

参数传递

通过 --param key=value 传入模型参数，可重复使用：

# 嵌套字段用点号
vtrix run kirin_v2_6_i2v \
  --param camera_control.type=simple \
  --param camera_control.config.horizontal=5

# 数组用 JSON 字符串
vtrix run spark_dance_v2_0 \
  --param content='[{"type":"text","text":"a cat running in rain"}]'

CLI 会根据模型 spec 自动做类型转换和校验（枚举、范围、必填等）。使用 vtrix models spec <model_id> 可查看当前模型的完整参数规格。

标志

标志	说明
--param key=value	模型参数，可重复。支持点号嵌套，数组用 JSON 字符串。
--output	url 仅输出结果 URL / json 完整响应，默认人类可读格式
--timeout	最大等待秒数，默认 600。退出码 0 = 成功，1 = 错误。
--dry-run	全局标志，打印将要发送的请求，不实际执行。

---

示例：图像转视频

使用 kirin_v3_i2v 将一张静态图像生成为动态视频。

先查看参数规格：

vtrix models spec kirin_v3_i2v

Model: kirin_v3_i2v
Name:  Kirin V3 I2V
Type:  video

Parameters:
  image_url          string    required   输入图像 URL

  prompt             string    optional   运动描述提示词
                                          默认: ""

  negative_prompt    string    optional   负向提示词
                                          默认: ""

  resolution         string    optional   输出分辨率
                                          值: 480p | 720p | 1080p
                                          默认: 720p

  duration           integer   optional   视频时长（秒），范围 3–10
                                          默认: 5

  seed               integer   optional   随机种子，-1 随机
                                          默认: -1

演练模式验证参数（不消耗积分）：

vtrix --dry-run run kirin_v3_i2v \
  --param image_url="https://example.com/landscape.jpg" \
  --param prompt="gentle wind, grass swaying slowly" \
  --param duration=6 \
  --param resolution=1080p

[dry-run] POST /model/v1/generation
{
  "model": "kirin_v3_i2v",
  "params": {
    "image_url": "https://example.com/landscape.jpg",
    "prompt": "gentle wind, grass swaying slowly",
    "duration": 6,
    "resolution": "1080p"
  }
}

正式提交，等待结果 URL：

vtrix run kirin_v3_i2v \
  --param image_url="https://example.com/landscape.jpg" \
  --param prompt="gentle wind, grass swaying slowly" \
  --param duration=6 \
  --param resolution=1080p \
  --output url

Submitting task...
✓ Task created: task_xyz789

Waiting for result...
████████████████████████░  96%  ~3s remaining

✓ Done
  https://cdn.vtrix.ai/outputs/task_xyz789/output.mp4

仅获取 URL 供脚本直接消费：

VIDEO_URL=$(vtrix run kirin_v3_i2v \
  --param image_url="https://example.com/landscape.jpg" \
  --param prompt="gentle wind, grass swaying slowly" \
  --output url)

echo "Result: $VIDEO_URL"