Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt

Use this file to discover all available pages before exploring further.

modellix-cli is the official command-line tool for Modellix. It helps you call the Modellix async model API from terminal and automate workflows in scripts or AI agents. For full API behavior and response fields, see the official REST API docs.

​
What You Can Do

  • Create async model generation tasks
  • Query task status and final generation result

​
Install

npm install -g modellix-cli
modellix-cli --version

​
Authentication

You can provide API key in either way:
  1. Recommended: environment variable MODELLIX_API_KEY
  2. Alternative: --api-key flag in each command
# macOS / Linux
export MODELLIX_API_KEY="your_api_key"

# Windows PowerShell
$env:MODELLIX_API_KEY="your_api_key"

​
Create a Task

​
Use inline JSON body

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

​
Use JSON file body

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

​
Common flags

  • --model-slug (required): model slug in provider/model format, for example bytedance/seedream-4.5-t2i
  • --body: request JSON string
  • --body-file: path to request JSON file
  • --api-key: API key (overrides MODELLIX_API_KEY)
Example success response: 
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "model_id": "alibaba/qwen-image-plus",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-abc123"
    }
  }
}

​
Query Task Result

Use the returned task_id: 
modellix-cli task get task-abc123
Example success response: 
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-abc123",
    "result": {
      "resources": [
        {
          "url": "https://cdn.example.com/images/abc123.png",
          "type": "image"
        }
      ]
    }
  }
}
  1. Run modellix-cli model invoke ... and copy the returned task_id.
  2. Run modellix-cli task get <task_id> to get status and result.
modellix-cli model invoke returns immediately with a task_id, so you need to poll task get to track progress.

​
Error Handling Guide

The CLI surfaces API errors directly. Use the error code to decide whether to fix inputs or retry.
  • 400: fix parameters or request body format before retrying.
  • 401: your API key is missing, invalid, or expired. Verify MODELLIX_API_KEY or pass --api-key.
  • 402: your account balance is insufficient. Recharge in the Modellix console and retry.
  • 404: verify task_id and --model-slug.
  • 429: you hit rate or concurrency limits. Retry with exponential backoff (for example: 1s, 2s, 4s).
  • 500 / 503: temporary server-side issue. Retry up to 3 times with backoff.

​
Help

modellix-cli --help
modellix-cli model invoke --help
modellix-cli task get --help