> ## Documentation Index
> Fetch the complete documentation index at: https://www.carrothub.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# carrothub 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

```bash theme={null}
carrothub run <endpoint> [--param value ...] [options]
```

## Endpoint identifier

Same as [`carrothub params`](https://www.carrothub.ai/docs/cli/commands/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.

```bash theme={null}
carrothub 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
`carrothub 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.

```bash theme={null}
carrothub 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
[`carrothub status`](https://www.carrothub.ai/docs/cli/commands/status). Use this when generation may take
longer than `--max-wait`, or when running inside a short-lived CI step.

```bash theme={null}
carrothub 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: carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-...
# Wait:         carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... --wait
```

## Output formats

### Text (default)

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

Results:
  https://cdn.carrothub.ai/.../video-0.mp4
```

### JSON (`--json`)

```json theme={null}
{
  "task_id": "9d2b8c1a-...",
  "status": "succeeded",
  "videos": [
    "https://cdn.carrothub.ai/.../video-0.mp4"
  ],
  "data": { ... }
}
```

The result key (`videos`, `images`, `audios`) matches the `result_key` field
shown by [`carrothub params`](https://www.carrothub.ai/docs/cli/commands/params).

## Examples

```bash theme={null}
# Text-to-image
carrothub run google/nano-banana-2/generation \
  --prompt "A serene mountain lake" \
  --resolution 2K

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

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

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

# Async submission + polling
carrothub 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

* [`carrothub status`](https://www.carrothub.ai/docs/cli/commands/status) — poll an existing task
* [Async workflows](https://www.carrothub.ai/docs/cli/workflows/async-tasks.md)
* [Scripting with JSON](https://www.carrothub.ai/docs/cli/workflows/json-output.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.