Modellix Skill

Modellix is a Model-as-a-Service (MaaS) platform providing unified API access to 100+ AI models for image and video generation. All models — regardless of provider (Alibaba, ByteDance, Kling, MiniMax) — share the same async API pattern: submit a task, get a task_id, poll for results.

Workflow

Follow these steps to integrate any Modellix model. This mirrors the official usage process.

Step 1: Obtain an API Key

Direct the user to create an API key:

1. Log in to the Modellix console
2. Navigate to API Key and create a new key
3. Save the key immediately — it is only displayed once after creation

Store the key securely as an environment variable (e.g., MODELLIX_API_KEY). Never hardcode it.

Step 2: Find the Right Model

The model catalog is in references/REFERENCE.md. Read that file to search for the model that fits the user's task. Each entry follows this pattern:

- [Model Name](https://docs.modellix.ai/{provider}/{model-slug}.md): Description

How to select a model:

1. Identify the task type: text-to-image, text-to-video, image-to-image, image-to-video, or specialized (try-on, outpainting, style transfer, etc.)
2. Search REFERENCE.md for models matching that task type
3. Compare model descriptions to find the best fit (e.g., speed vs quality tradeoffs — "turbo" models are faster/cheaper, "plus"/"pro" models are higher quality)

After selecting a model, fetch its API documentation by visiting the URL from REFERENCE.md (e.g., https://docs.modellix.ai/alibaba/qwen-image-plus.md). The model's doc page contains the OpenAPI spec with:

• The exact API endpoint path
• Required and optional request parameters (with types, defaults, and allowed values)
• Request/response examples

This step is essential because each model has different parameters (e.g., size format, seed range, model-specific options). Always read the model's doc page before writing API calls.

Step 3: Submit an Async Task

All Modellix API calls are asynchronous. Submit a task with a POST request:

POST https://api.modellix.ai/api/v1/{type}/{provider}/{model_id}/async

Path parameters:

Parameter	Description	Examples
type	Task type	text-to-image, text-to-video, image-to-image, image-to-video
provider	Model provider	alibaba, bytedance, kling, minimax
model_id	Model identifier	qwen-image-plus, seedream-4.5-t2i, kling-v2.1-t2i

Example — generate an image with Qwen Image Plus:

curl -X POST https://api.modellix.ai/api/v1/text-to-image/alibaba/qwen-image-plus/async \
  -H "Authorization: Bearer $MODELLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cute cat playing in a garden on a sunny day"}'

Successful submission returns a task_id:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "model_id": "qwen-image-plus",
    "duration": 150
  }
}

A code of 0 means success. Any other value indicates an error (see Error Handling below).

Step 4: Poll for Results

Query the task status using the task_id:

curl -X GET https://api.modellix.ai/api/v1/tasks/{task_id} \
  -H "Authorization: Bearer $MODELLIX_API_KEY"

Task statuses:

Status	Meaning	Action
pending	Queued or processing	Wait 2-5 seconds, poll again
success	Generation complete	Extract results from data.result
failed	Generation failed	Check error message

Successful result example:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-abc123",
    "model_id": "qwen-image-plus",
    "duration": 3500,
    "result": {
      "resources": [
        {
          "url": "https://cdn.example.com/images/abc123.png",
          "type": "image",
          "width": 1024,
          "height": 1024,
          "format": "png",
          "role": "primary"
        }
      ],
      "metadata": {
        "image_count": 1,
        "request_id": "req-123456"
      },
      "extensions": {
        "submit_time": "2024-01-01T10:00:00Z",
        "end_time": "2024-01-01T10:00:03Z"
      }
    }
  }
}

The generated content URLs are in data.result.resources. Download or use them promptly — results expire after 24 hours.

Implement polling with exponential backoff (1s, 2s, 4s...) rather than fixed intervals. A typical image takes 3-10 seconds; video generation takes longer (30-120 seconds depending on model and duration).

Step 5: Handle Results

Extract the generated content from the resources array:

for resource in data["result"]["resources"]:
    url = resource["url"]        # download URL
    media_type = resource["type"]  # "image" or "video"
    # Download and save before the 24-hour expiration

Error Handling

All errors follow a unified format:

{
  "code": 400,
  "message": "Invalid parameters: parameter 'prompt' is required"
}

The code field equals the HTTP status code. The message contains a category and detail separated by : .

HTTP Status	Description	Common Scenarios	Retryable
400	Bad Request	Missing or invalid parameters	No — fix parameters first
401	Unauthorized	Invalid or missing API key	No — provide a valid key
404	Not Found	Task ID or model not found	No — check resource ID
429	Too Many Requests	Rate or concurrency limit exceeded	Yes — use exponential backoff
500	Internal Server Error	Unexpected server error	Yes — retry up to 3 times
503	Service Unavailable	Provider temporarily down	Yes — retry with backoff

Implementation Patterns

Modellix has no SDK — all integration is done via REST API calls. Below are reference patterns for common languages. Adapt these to the user's project as needed.

Python (requests)

import requests, time, os

API_KEY = os.environ["MODELLIX_API_KEY"]
BASE = "https://api.modellix.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Step 1: Submit task
resp = requests.post(f"{BASE}/text-to-image/alibaba/qwen-image-plus/async",
                     headers=HEADERS, json={"prompt": "A cat in a garden"})
task_id = resp.json()["data"]["task_id"]

# Step 2: Poll with exponential backoff
wait = 2
while True:
    time.sleep(wait)
    result = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS).json()
    if result["data"]["status"] == "success":
        print(result["data"]["result"]["resources"][0]["url"])
        break
    if result["data"]["status"] == "failed":
        raise Exception(result["data"])
    wait = min(wait * 2, 10)

Node.js (fetch)

const API_KEY = process.env.MODELLIX_API_KEY;
const BASE = "https://api.modellix.ai/api/v1";
const headers = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// Submit task
const submitRes = await fetch(`${BASE}/text-to-image/alibaba/qwen-image-plus/async`, {
  method: "POST", headers, body: JSON.stringify({ prompt: "A cat in a garden" }),
});
const { data: { task_id } } = await submitRes.json();

// Poll with backoff
let wait = 2000;
while (true) {
  await new Promise(r => setTimeout(r, wait));
  const pollRes = await fetch(`${BASE}/tasks/${task_id}`, { headers });
  const { data } = await pollRes.json();
  if (data.status === "success") { console.log(data.result.resources[0].url); break; }
  if (data.status === "failed") { throw new Error(JSON.stringify(data)); }
  wait = Math.min(wait * 2, 10000);
}

Batch Processing

When submitting multiple tasks, respect the concurrent task limit (typically 3 per team). Use a semaphore or queue to throttle parallel submissions.

Common Pitfalls

• API key shown once: Save immediately. Lost keys require creating a new one.
• Results expire in 24 hours: Download generated content promptly.
• All operations are async: There is no synchronous endpoint. Always poll for results.
• Rate limits are team-wide: All API keys under the same team share limits.
• Concurrent task limit: Typically 3 per team. Exceeding this triggers 429 errors.
• Parameter formats vary by model: Always read the model's API doc. For example, size might be "1024*1024" (asterisk) for Alibaba models or "2048x2048" (letter x) for ByteDance models.
• Polling too fast wastes resources: Use exponential backoff, not fixed sub-second intervals.

Verification Checklist

Before shipping a Modellix integration:

• API key stored as environment variable, not hardcoded
• Authorization: Bearer <key> header set correctly
• Model-specific parameters match the model's API doc (read from REFERENCE.md → model doc page)
• Task submission returns valid task_id (check code == 0)
• Polling handles all statuses: pending, success, failed
• Exponential backoff implemented for polling and retries
• Retryable (429/500/503) vs non-retryable (400/401/404) errors handled differently
• Results downloaded/stored before 24-hour expiration
• Concurrent task limit respected (semaphore or queue)
• Appropriate timeouts set (30-60s for images, 60-120s for videos)

Resources

• Model Catalog: Read references/REFERENCE.md to find available models and their doc page URLs
• API Usage Guide: https://docs.modellix.ai/ways-to-use/api
• Pricing: https://docs.modellix.ai/get-started/pricing
• Full Doc Index: https://docs.modellix.ai/llms.txt