We’re excited to release modellix-cli — the official command-line tool for the Modellix platform.

If you’ve been using the Modellix REST API to generate images and videos, you can now do the same thing directly from your terminal — no HTTP client setup, no boilerplate code. Just install, authenticate, and invoke.

Why a CLI?

The REST API is great for production integrations, but many workflows don’t need a full application:

  • Quick prototyping — Test a model with a single command before writing any integration code.
  • Shell scripting — Chain image or video generation into bash scripts, cron jobs, or CI pipelines.
  • AI agent tooling — Give your AI agents a lightweight, non-interactive interface to call Modellix models programmatically.
  • Batch processing — Loop through prompts in a file and generate assets in bulk.

modellix-cli is built for these use cases — fast, scriptable, and agent-friendly.

Install

One command via npm:

1
npm install -g modellix-cli

Verify:

1
modellix-cli --version

The package is lightweight at 23.5 KB unpacked, with only 2 runtime dependencies. It’s built with TypeScript on the oclif framework and licensed under MIT.

Authentication

Set your API key once as an environment variable:

1
2
# macOS / Linux
export MODELLIX_API_KEY="your_api_key"
1
2
# Windows PowerShell
$env:MODELLIX_API_KEY="your_api_key"

Or pass it per command with --api-key. Get your key from the Modellix Console.

Two Commands, Full Workflow

The CLI covers the complete Modellix async workflow in two commands.

1. Create a generation task

Pass your prompt inline:

1
2
3
modellix-cli model invoke \
  --model-slug bytedance/seedream-4.5-t2i \
  --body '{"prompt":"A cute cat playing in a garden on a sunny day"}'

Or reference a JSON file for complex payloads:

1
2
3
modellix-cli model invoke \
  --model-slug alibaba/qwen-image-edit \
  --body-file ./payload.json

The command returns immediately with a task_id and a get_result command you can copy to check the result:

1
2
3
4
5
6
7
8
9
10
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "model_id": "bytedance/seedream-4.5-t2i",
    "get_result": "modellix-cli task get task-abc123"
  }
}

2. Query the result

Poll with the returned task_id:

1
modellix-cli task get task-abc123

Once the task completes, you get the generated asset URL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-abc123",
    "result": {
      "resources": [
        {
          "url": "https://cdn.example.com/images/abc123.png",
          "type": "image"
        }
      ]
    }
  }
}

Example: Batch Image Generation in Bash

Here’s a practical example — generate images for a list of prompts and download the results:

1
2
3
4
5
6
7
8
9
10
11
#!/bin/bash
prompts=("A sunset over the ocean" "A cyberpunk cityscape at night" "A watercolor painting of mountains")

for prompt in "${prompts[@]}"; do
  result=$(modellix-cli model invoke \
    --model-slug bytedance/seedream-4.5-t2i \
    --body "{\"prompt\":\"$prompt\"}")

  task_id=$(echo "$result" | jq -r '.data.task_id')
  echo "Created task: $task_id for prompt: $prompt"
done

Error Handling

The CLI surfaces API errors directly with clear HTTP status codes:

Code Meaning Action
400 Invalid parameters Fix your request body or flags
401 Authentication failed Check your MODELLIX_API_KEY
402 Insufficient balance Recharge your account
429 Rate limit hit Retry with exponential backoff
500 / 503 Server-side issue Retry up to 3 times with backoff

Built-in Help

Every command has detailed help:

1
2
3
modellix-cli --help
modellix-cli model invoke --help
modellix-cli task get --help

Get Started

  1. Install: npm install -g modellix-cli
  2. Set your key: export MODELLIX_API_KEY="your_key"
  3. Generate: modellix-cli model invoke --model-slug bytedance/seedream-4.5-t2i --body '{"prompt":"Hello world"}'

For the full reference, check out the CLI documentation.

Have feedback or feature requests? Open an issue on GitHub or reach out on Discord.