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

# Set Up AI Agents on Modellix

> Set up an AI agent with one Modellix API key for Media Models, the LLM gateway, and optional Web Tools. Use async polling for media; call LLM and Tools synchronously.

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

Modellix is a MaaS platform. One Modellix API key covers **Media Models** and **LLMs**. Web Search and Web Fetch are optional Tools. Pick the host that matches the job—do not send media generation to the LLM gateway, and do not poll LLM or Tools responses.

| Job | Host | Call style |
| - | - | - |
| Image, video, or speech generation | `https://api.modellix.ai` | Async: submit a task, then poll |
| Chat, coding, or text generation | `https://llm.modellix.ai` | Sync (optional SSE) |
| Public web results or page content | `https://tool.modellix.ai` | Sync |

Human-oriented product map: [Platform Overview](/get-started/overview).

## Prerequisite: Create an API Key

A human must create a Modellix account and generate an API key. Create one in the [console](https://modellix.ai/console/api-key). With that key, your agent can call Media Models, LLM, and Web Tools.

<Note>
  The API key is displayed only once after creation. Store it securely, typically as `MODELLIX_API_KEY`.
</Note>

## Agent Skills

The official Modellix Skill teaches coding agents how to discover media models, inspect request schemas, and generate images, videos, and speech. It does not replace the [LLM Overview](/llm/overview) for chat gateway setup.

Install via skills.sh:

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

Target one agent:

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

<Card title="Agent Skill" icon="wrench" href="/ways-to-use/skill">
  Installation for Cursor, Claude Code, GitHub Copilot, Codex, and other Agent Skills hosts.
</Card>

## Modellix CLI

`modellix-cli` creates **media** generation tasks and fetches results from the terminal. Use it for async image, video, and speech workflows—not for LLM chat.

```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 run \
  --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">
  Authentication, `model run --wait`, schemas, and task downloads.
</Card>

## Media Models: Async Two-Step

Media generation uses `https://api.modellix.ai`. Copy the prompt below for your agent, or open it in Cursor.

<Prompt description="Agent quick start for async media generation." icon="bolt" actions={["copy", "cursor"]}>
  Modellix **Media Models** use an asynchronous two-step pattern. Do not apply this pattern to `https://llm.modellix.ai` or `https://tool.modellix.ai`.

  ### The Two-Step Pattern

  1. **Create Task (`POST`)**: Send generation parameters to the model's endpoint on `https://api.modellix.ai`. The API responds immediately with a `task_id` and a status of `pending`.
  2. **Poll Result (`GET`)**: Query `https://api.modellix.ai/api/v1/tasks/{task_id}` until `status` is `success` or `failed`.

  ### Error Handling

  | 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) {
    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;

    const pollUrl = `https://api.modellix.ai/api/v1/tasks/${taskId}`;

    while (true) {
      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') {
        return pollData.data.result.resources;
      } else if (status === 'failed') {
        throw new Error(`Task failed: ${pollData.data.error_message || 'Unknown error'}`);
      }
    }
  }
  ```
</Prompt>

Full media workflow: [REST API](/ways-to-use/api).

## LLM: Synchronous Chat

The LLM gateway at `https://llm.modellix.ai` returns text in one response (optional SSE). Pass `model` as a `provider/name` ID. Do not poll and do not mix Chat Completions fields with Messages fields.

| Client type | Base URL | Protocol |
| - | - | - |
| OpenAI SDK, Codex, Cursor, OpenCode (OpenAI mode) | `https://llm.modellix.ai/v1` | Chat Completions or Responses |
| Anthropic SDK, Claude Code | `https://llm.modellix.ai` (no `/v1`) | Messages |

<Prompt description="Agent quick start for the Modellix LLM gateway." icon="message-square" actions={["copy", "cursor"]}>
  Modellix **LLM** is a synchronous gateway at `https://llm.modellix.ai`. Do not create media tasks on this host. Do not poll.

  ### Auth and Model IDs

  Use a Modellix API key (Bearer or `x-api-key`), not a vendor platform key. Set `model` to a `provider/name` ID from [https://www.modellix.ai/llm](https://www.modellix.ai/llm) (for example `openai/gpt-5.6-sol` or `anthropic/claude-sonnet-5`).

  ### Base URLs

  * OpenAI-compatible Chat Completions / Responses: `https://llm.modellix.ai/v1`
  * Anthropic-compatible Messages: `https://llm.modellix.ai` (no `/v1`)

  ### Minimal Chat Completions Example

  ```bash theme={null}
  curl -sS "https://llm.modellix.ai/v1/chat/completions" \
    -H "Authorization: Bearer ${MODELLIX_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.6-sol",
      "stream": false,
      "max_tokens": 256,
      "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
    }'
  ```

  ### Error Handling

  | Code | Action |
  | - | - |
  | **400** | **Do not retry**. Fix the request body or protocol fields. |
  | **401** | **Do not retry**. Verify the Modellix API key. |
  | **402** | **Do not retry**. Insufficient balance (`insufficient_quota`). |
  | **404** | **Do not retry**. Unknown path or model unavailable. |
  | **429** | **Retry with backoff**. Rate limit or model temporarily unavailable. |
  | **5xx** | **Retry with backoff**. Temporary upstream or service error. |

  Protocols, multimodal inputs, and billing: [https://docs.modellix.ai/llm/overview](https://docs.modellix.ai/llm/overview)
</Prompt>

<Card title="LLM Overview" icon="message-square" href="/llm/overview">
  Protocols, SDK overrides, coding tools, and token billing.
</Card>

## Web Tools

Web Search and Web Fetch at `https://tool.modellix.ai` are optional. Use them when the user needs live public web results or readable page content. Calls are synchronous. REST requires `X-Mdlx-User-Id`. MCP clients can connect to `https://tool.modellix.ai/mcp`.

<Columns cols={2}>
  <Card title="Tools Overview" icon="wrench" href="/tools/overview">
    Web Search, Web Fetch, headers, and per-request pricing.
  </Card>

  <Card title="Web Tools MCP" icon="blocks" href="/tools/mcp">
    Streamable HTTP MCP for Cursor, Claude Code, Codex, and other clients.
  </Card>
</Columns>