vtrix run

Usage

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

The command polls automatically and outputs the result to stdout when the task completes. Progress information is written to stderr.

# Text to video
vtrix run spark_dance_v2_0 \
  --param prompt="neon cityscape timelapse" \
  --param duration=5 \
  --output url

# Image to video
vtrix run kirin_v2_6_i2v \
  --param image=https://example.com/cat.jpg \
  --output url

# Dry-run mode (global flag — prints the request without sending it, no login required)
vtrix --dry-run run spark_dance_v2_0 --param prompt="neon city"

Passing Parameters

Pass model parameters with --param key=value. The flag can be repeated:

# Nested fields use dot notation
vtrix run kirin_v2_6_i2v \
  --param camera_control.type=simple \
  --param camera_control.config.horizontal=5

# Arrays use JSON strings
vtrix run spark_dance_v2_0 \
  --param content='[{"type":"text","text":"a cat running in rain"}]'

The CLI automatically performs type coercion and validation (enums, ranges, required fields) based on the model spec. Use vtrix models spec <model_id> to view the full parameter spec for any model.

Flags

Flag	Description
--param key=value	Model parameter, repeatable. Supports dot notation for nesting; use JSON strings for arrays.
--output	url outputs result URL only / json full response / default is human-readable format
--timeout	Max wait time in seconds, default 600. Exit code 0 = success, 1 = error.
--dry-run	Global flag — prints the request that would be sent without executing it.

---

Example: Image to Video

Using kirin_v3_i2v to animate a static image.

Check the parameter spec first:

vtrix models spec kirin_v3_i2v

Model: kirin_v3_i2v
Name:  Kirin V3 I2V
Type:  video

Parameters:
  image_url          string    required   Input image URL

  prompt             string    optional   Motion description prompt
                                          Default: ""

  negative_prompt    string    optional   Negative prompt
                                          Default: ""

  resolution         string    optional   Output resolution
                                          Values: 480p | 720p | 1080p
                                          Default: 720p

  duration           integer   optional   Video duration in seconds, range 3–10
                                          Default: 5

  seed               integer   optional   Random seed, -1 for random
                                          Default: -1

Validate parameters with dry-run (no credits spent):

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"
  }
}

Submit and wait for the result 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

Capture the URL directly in a script:

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"