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

# AI Onboarding

> Everything you need to onboard your AI agent to Modellix.

> If you are an AI agent, this document provides the essential context and tools you need to interact with Modellix.

Modellix provides a unified API for cutting-edge AI image and video generation models. Since media generation tasks can take some time, **Modellix uses an asynchronous API design**.

Here are the resources and patterns you should use to integrate Modellix into your workflows.

## Prerequisite: Create an API Key

Currently, we require a human to create a Modellix account and generate an API Key. Once you have an account, you'll need to [create an API key](https://modellix.ai/console/api-key) in the console. With an API key, your agent can perform all other tasks.

<Note>
  The API Key is only displayed once after creation. Ensure it is securely stored, typically as a `MODELLIX_API_KEY` environment variable.
</Note>

## Agent Skills

Skills give AI agents specialized knowledge for specific tasks. We provide an official Modellix skill that helps you construct API requests correctly and understand the available models.

You can install the Modellix skill with a single command via Smithery:

```bash theme={null}
npx @smithery/cli@latest skill add modellix/modellix-skill
```

Or directly from GitHub:

```bash theme={null}
npx skills add https://github.com/Modellix/modellix-skill/tree/main/modellix-skill
```

<Card title="Agent Skill" icon="wrench" href="/ways-to-use/skill">
  View installation instructions for Cursor, Claude Code, GitHub Copilot, Codex, and other AI agents.
</Card>

## Modellix CLI

The Modellix CLI (`modellix-cli`) lets you create generation tasks and fetch results directly from the terminal. It's perfect for agentic workflows and automated scripts.

```bash theme={null}
# Install the CLI
npm install -g modellix-cli

# Export the API key
export MODELLIX_API_KEY="your_api_key"

# Create a generation task
modellix-cli model invoke \
  --model-slug alibaba/qwen-image-edit \
  --body '{"prompt":"A cute cat playing in a garden on a sunny day"}'

# Fetch the task result using the returned task_id
modellix-cli task get task-abc123
```

<Card title="Modellix CLI" icon="terminal" href="/ways-to-use/cli">
  Learn more about using the CLI for async model generation workflows.
</Card>

## Quick Start Guide

Throughout our documentation, we provide quick start guides for common tasks. Copy the prompt for your agent or click to open in Cursor.

<Prompt description="Agent quick start guide for async model generation." icon="bolt" actions={["copy", "cursor"]}>
  Modellix uses an **asynchronous two-step pattern** for all model generations.

  ### The Two-Step Pattern

  1. **Create Task (`POST`)**: Send the generation parameters to the model's endpoint. The API responds immediately with a `task_id` and a status of `pending`.
  2. **Poll Result (`GET`)**: Periodically query the task status using the `task_id` until the status changes to `success` or `failed`.

  ### Error Handling & Best Practices

  Always implement these rules for production stability:

  | Code        | Action                                                                           |
  | ----------- | -------------------------------------------------------------------------------- |
  | **400**     | **Do not retry**. Fix parameters or request body format.                         |
  | **401**     | **Do not retry**. Verify the API key is provided and valid.                      |
  | **402**     | **Do not retry**. Account balance is insufficient. Human intervention required.  |
  | **404**     | **Do not retry**. Verify the `task_id` or `model-slug`.                          |
  | **429**     | **Retry with exponential backoff**. You hit rate or concurrency limits.          |
  | **500/503** | **Retry with exponential backoff** (up to 3 times). Temporary server-side issue. |

  ### Minimal Polling Example (Node.js)

  ```javascript theme={null}
  const API_KEY = process.env.MODELLIX_API_KEY;
  const MODEL_URL = 'https://api.modellix.ai/api/v1/alibaba/qwen-image-plus/async';

  async function generateImage(prompt) {
    // 1. Create the task
    const createRes = await fetch(MODEL_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ prompt })
    });
    
    const createData = await createRes.json();
    if (createData.code !== 0) throw new Error(`Task creation failed: ${createData.message}`);
    
    const taskId = createData.data.task_id;
    console.log(`Task created: ${taskId}. Polling for results...`);

    // 2. Poll for the result
    const pollUrl = `https://api.modellix.ai/api/v1/tasks/${taskId}`;
    
    while (true) {
      // Wait for 3 seconds between polls
      await new Promise(resolve => setTimeout(resolve, 3000));
      
      const pollRes = await fetch(pollUrl, {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      });
      
      const pollData = await pollRes.json();
      if (pollData.code !== 0) throw new Error(`Polling failed: ${pollData.message}`);
      
      const status = pollData.data.status;
      
      if (status === 'success') {
        console.log('Generation complete!');
        // The generated resources are in result.resources
        return pollData.data.result.resources;
      } else if (status === 'failed') {
        throw new Error(`Task failed: ${pollData.data.error_message || 'Unknown error'}`);
      }
      
      // If status is 'pending' or 'processing', loop continues
      console.log(`Status: ${status}...`);
    }
  }
  ```
</Prompt>