mulerouter run

Invoke a model endpoint and wait for the result

run is the workhorse command. It submits a generation task to the configured site and — by default — polls until the task completes, then prints the result URLs.

Synopsis

mulerouter run <endpoint> [--param value ...] [options]

Endpoint identifier

Same as mulerouter params:

Form	Behavior
<provider>/<model>	Auto-resolves the action if the model has exactly one
<provider>/<model>/<action>	Explicit action (generation, edit, …)

Model parameters

Pass model parameters as flags using kebab-case versions of the parameter names. Both --key value and --key=value syntax are accepted.

mulerouter run alibaba/wan2.6-t2v \
  --prompt "A cat walking through a garden" \
  --duration 10 \
  --size "1280*720"

The CLI validates and coerces values based on the parameter’s type:

Type	Accepted CLI value
string	Any value
integer	Parsed with Number.parseInt. Invalid values throw.
number	Parsed with Number.parseFloat. Invalid values throw.
boolean	true or false, or the bare flag itself (e.g. --audio ≡ --audio true)
array	Must be a valid JSON array string, e.g. --images '["https://..."]'

If a parameter declares an enum, the supplied value must match (use mulerouter params <endpoint> to see allowed values).

Missing required parameters and empty strings for required string parameters produce a friendly error before any HTTP call is made.

Common options

Option	Default	Description
--api-key <key>	env	Override API key
--base-url <url>	env	Override base URL
--site <site>	env	Override site filter for the request
--no-wait	—	Submit the task and exit immediately (don’t poll)
--poll-interval <s>	20	Polling interval in seconds
--max-wait <s>	900	Maximum wait time in seconds (15 min)
--quiet	—	Suppress progress lines on stderr
--json	—	Machine-readable output on stdout
--extra <KEY=VALUE>	—	Inject an extra parameter not declared in the catalog. Repeatable.

--extra values are parsed as JSON when possible — --extra count=3 sets the number 3, while --extra label=draft sets the string "draft". You can also pass undeclared parameters directly as --anything value; the CLI forwards unknown flags in the request body.

Local image inputs

Any parameter whose name implies an image (image, images, first_frame, last_frame, mask, …) accepts:

• An HTTPS URL — passed through unchanged.
• A data: URI — passed through unchanged.
• A local file path — read, validated, and converted to a base64 data URI before being sent.

mulerouter run alibaba/wan2.6-i2v \
  --image ./photo.png \
  --prompt "Slow zoom in" \
  --duration 5

Supported formats: .png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff, .tif, .svg, .ico, .heic, .heif, .avif. Files are capped at 20 MB; paths inside sensitive directories (/etc, ~/.ssh, ~/.aws, …) are blocked.

If you point at a local path that doesn’t exist, the CLI prints a yellow warning and still attempts the request (treating the string as a URL) so that typos fail loudly rather than silently.

Synchronous vs async

Synchronous (default). The CLI calls POST then loops with GET requests every --poll-interval seconds, logging status changes to stderr. When the task reaches a terminal state, the result is printed to stdout. The process exits non-zero if the task failed.

Async (--no-wait). The CLI submits the task and prints the resulting task_id and api_path so you can resume later with mulerouter status. Use this when generation may take longer than --max-wait, or when running inside a short-lived CI step.

mulerouter run alibaba/wan2.6-t2v --prompt "Long cinematic shot" --no-wait
# Task ID:  9d2b8c1a-...
# API Path: /vendors/alibaba/v1/wan2.6-t2v/generation
# Status:   created (not waiting for completion)
#
# Check status: mulerouter status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-...
# Wait:         mulerouter status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... --wait

Output formats

Text (default)

Task ID: 9d2b8c1a-...
Status:  succeeded

Results:
  https://cdn.mulerouter.ai/.../video-0.mp4

JSON (--json)

{
  "task_id": "9d2b8c1a-...",
  "status": "succeeded",
  "videos": [
    "https://cdn.mulerouter.ai/.../video-0.mp4"
  ],
  "data": { ... }
}

The result key (videos, images, audios) matches the result_key field shown by mulerouter params.

Examples

# Text-to-image
mulerouter run google/nano-banana-2/generation \
  --prompt "A serene mountain lake" \
  --resolution 2K

# Text-to-video with audio
mulerouter run alibaba/wan2.6-t2v \
  --prompt "Rain falling on a glass roof" \
  --duration 15 \
  --audio

# Image-to-video from a local file
mulerouter run alibaba/wan2.6-i2v \
  --image ./hero.jpg \
  --prompt "Gentle parallax with drifting clouds"

# Text-to-speech (MiniMax)
mulerouter run minimax/speech-2.8-turbo \
  --prompt "Welcome to MuleRouter." \
  --voice-id "Charming_Lady"

# Async submission + polling
mulerouter run alibaba/wan2.6-t2v --prompt "..." --no-wait --json \
  | tee task.json

Exit codes

Code	Meaning
0	Task completed successfully
1	Validation error, configuration error, transport error, or non-success terminal status (failed, etc.)

See also

• mulerouter status — poll an existing task
• Async workflows
• Scripting with JSON