> ## 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 Plugin for Coding Agents

> Install the official Modellix Plugin in Claude Code, Codex, Cursor, and other agent hosts to generate images, videos, and speech via CLI or REST API.

The [Modellix Plugin](https://github.com/Modellix/modellix-plugin) packages everything your coding agent needs to generate images, videos, and speech audio with [Modellix](https://modellix.ai): the official Modellix skill, model discovery guidance, default model choices, credential handling, and retry rules that match the CLI exit codes.

For a visual Excalidraw workspace with image prepare/confirm, HTML drafts, and presentations, see [Agent Canvas](/ways-to-use/agent-canvas) instead.

The repository follows the [Open Plugins](https://open-plugins.com/plugin-builders/specification) specification, so the same layout installs into Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, Hermes, and any Agent Skills host.

## Plugin or Skill

The repository ships in two shapes. Pick the one your host supports.

| Install shape | What you get | When to use it |
| - | - | - |
| **Plugin** | Repository root: plugin manifests plus `skills/modellix` | Your host has a plugin marketplace (Claude Code, Codex, Cursor, OpenClaw, Pi) |
| **Skill** | Only the `skills/modellix` Agent Skill | Your host has no plugin marketplace, or you only want the skill |

<Note>
  If you only need the Agent Skill, see the [Skill](/ways-to-use/skill) guide, which covers the standalone `modellix-skill` repository as well.
</Note>

## What the Plugin Provides

* A CLI-first workflow: `modellix-cli doctor` → `model run --wait` → `task download`
* Automatic REST fallback when the CLI is not installed
* Sensible default models when you do not name one
* Model discovery through `modellix-cli model list`, `model describe`, and `model get-schema`, plus the live model index at [llms.txt](https://docs.modellix.ai/llms.txt)
* Retry and error guidance aligned with CLI exit codes, including paid-submission safety rules
* Credential handling for `MODELLIX_API_KEY` and saved CLI auth profiles

## Requirements

* A Modellix API key from the [Modellix Console](https://www.modellix.ai/console/api-key)
* Recommended: [`modellix-cli`](https://www.npmjs.com/package/modellix-cli) on Node.js 18.17 or later

```bash theme={null}
npm install --global modellix-cli@latest
modellix-cli doctor --json
```

The plugin works without the CLI by calling the [REST API](/ways-to-use/api) directly, but the CLI gives your agent faster task submission, built-in waiting, and safer downloads.

## Install as a Plugin

<Tabs>
  <Tab title="Claude Code">
    Install:

    ```text theme={null}
    /plugin marketplace add Modellix/modellix-plugin
    /plugin install modellix@modellix
    ```

    Update:

    ```text theme={null}
    /plugin marketplace update modellix
    /plugin update modellix@modellix
    ```

    You can also use the `/plugin` UI, then run `/reload-plugins` if the plugin does not appear.

    For local development against a clone:

    ```bash theme={null}
    claude --plugin-dir /path/to/modellix-plugin
    claude plugin validate /path/to/modellix-plugin
    ```
  </Tab>

  <Tab title="Codex">
    Add the marketplace, then install `modellix` from the `/plugins` list:

    ```bash theme={null}
    codex plugin marketplace add Modellix/modellix-plugin
    ```

    To update, reopen `/plugins` and update from there, or re-add the marketplace and reinstall.
  </Tab>

  <Tab title="Cursor">
    Browse or submit the plugin through [cursor.directory](https://cursor.directory/plugins/new) using the repository URL `https://github.com/Modellix/modellix-plugin`.

    To install from a local clone:

    ```bash theme={null}
    git clone https://github.com/Modellix/modellix-plugin.git
    ln -sfn "$PWD/modellix-plugin" ~/.cursor/plugins/local/modellix
    ```

    Run **Developer: Reload Window**, then confirm the plugin under **Customize**.

    Update a symlinked clone:

    ```bash theme={null}
    git -C ~/.cursor/plugins/local/modellix pull
    ```

    Reload the window again after pulling.
  </Tab>

  <Tab title="OpenClaw">
    The ClawHub package `@modellix/modellix-plugin` ships the Open Plugins layout as a content and skill bundle, not a TypeScript runtime plugin.

    ```bash theme={null}
    openclaw plugins install clawhub:@modellix/modellix-plugin
    ```

    Install from a local checkout or Git instead:

    ```bash theme={null}
    openclaw plugins install .
    openclaw plugins install git:github.com/Modellix/modellix-plugin
    ```

    To update, reinstall from the same ClawHub, Git, or path source. `openclaw plugins update` only refreshes npm-tracked installs.
  </Tab>

  <Tab title="Pi">
    [Pi](https://github.com/badlogic/pi-mono) loads the repository as a [Pi package](https://docs.pi.dev/packages) that contributes skills only.

    ```bash theme={null}
    pi install git:github.com/Modellix/modellix-plugin
    ```

    Local checkouts work too:

    ```bash theme={null}
    pi install /path/to/modellix-plugin
    ```

    Update:

    ```bash theme={null}
    pi update --extensions
    ```
  </Tab>
</Tabs>

## Install as a Skill

When your host has no plugin marketplace, or you only want `skills/modellix`, install the Agent Skill instead:

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

The [Skill](/ways-to-use/skill) guide covers skill installs for skills.sh, ClawHub, OpenCode, Cursor, Pi, Hermes, and Smithery.

## Configure Your API Key

Every install shape reads the same credential.

```bash theme={null}
export MODELLIX_API_KEY="your_api_key"
```

The CLI resolves the key in this order: `--api-key`, then `MODELLIX_API_KEY`, then the selected saved profile.

* REST calls always require `MODELLIX_API_KEY`.
* The CLI can use the environment variable or a saved profile created by `modellix-cli auth login` or `modellix-cli init`.
* In Cursor, you can set the key as the `MODELLIX_API_KEY` plugin variable.
* In Hermes, prefer `~/.hermes/.env` or the secure prompt shown when the skill loads.

<Warning>
  Prefer session-only keys and persist them only when you intend to. Never commit an API key to a repository or print it in logs.
</Warning>

## Verify the Install

Confirm the environment first, then generate one asset end to end.

<Steps>
  <Step title="Check the CLI and Credentials">
    ```bash theme={null}
    modellix-cli doctor --json
    ```

    `doctor` reports the Node.js version, the API-key source, API connectivity, and your team balance without printing the key.
  </Step>

  <Step title="Ask Your Agent to Generate Something">
    ```text theme={null}
    Generate an image of a cinematic sunset over a futuristic city skyline.
    ```

    The plugin routes the request through the CLI, picks a default model, and waits for the task to finish.
  </Step>

  <Step title="Confirm the Output">
    The agent downloads results into your working directory. To reproduce the same flow manually:

    ```bash theme={null}
    modellix-cli model run \
      --model-slug google/nano-banana-2-lite \
      --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
      --wait --timeout 5m --json

    modellix-cli task download <task_id> --output-dir ./outputs --json
    ```
  </Step>
</Steps>

## Supported Task Types

| Type | Description |
| - | - |
| `text-to-image` | Generate images from text prompts |
| `image-to-image` | Edit or transform images with text instructions |
| `text-to-video` | Create videos from text descriptions |
| `image-to-video` | Convert static images into video sequences |
| `video-to-video` | Transform existing videos |

## Default Models

When you do not name a model, the plugin uses these defaults:

| Task type | Default model slug |
| - | - |
| Text-to-image | `google/nano-banana-2-lite` |
| Image editing / image-to-image | `google/nano-banana-2-lite-edit` |
| Text-to-video | `bytedance/seedance-2.0-mini-t2v` |
| Image-to-video | `bytedance/seedance-2.0-fast-i2v` |
| Video-to-video | `bytedance/seedance-2.0-fast-v2v` |

Name any other model in your prompt to override the default. To discover and inspect models:

```bash theme={null}
modellix-cli model list --type text-to-image --output slugs
modellix-cli model describe google/nano-banana-2 --json
modellix-cli model get-schema google/nano-banana-2
```

Request-body schemas come from `modellix-cli model get-schema` (JSON is the default; the endpoint is public and does not need an API key). See the [CLI schema command](/ways-to-use/cli#get-a-model-api-schema).

If the CLI is unavailable, the plugin uses Docs MCP when connected, then `docs_url` from `model describe`, or the model page in [llms.txt](https://docs.modellix.ai/llms.txt). The [Skill](/ways-to-use/skill#inspect-a-request-schema) guide covers when the agent fetches the schema versus when it skips the call.

## How the Plugin Runs Tasks

Understanding these rules helps you predict what your agent will do:

1. It prefers the CLI when installed, and falls back to the [REST API](/ways-to-use/api) otherwise.
2. It reads request schemas with `model get-schema` before non-trivial submits, and skips that call for documented default examples or a complete body you already supplied.
3. It uses `model run --wait` or `task wait` instead of hand-written polling loops.
4. It never blindly retries a paid `model run` after an unknown submission outcome. It checks `modellix-cli task history` first.
5. It may use the helper scripts bundled in `skills/modellix/scripts/`, and falls back to plain CLI commands if a helper fails.
6. It treats `modellix-cli --help` and the [npm package](https://www.npmjs.com/package/modellix-cli) as the source of truth for CLI behavior.

## Troubleshooting

| Problem | What to do |
| - | - |
| The agent does not use Modellix | Confirm the plugin or skill is installed and enabled, then start a new session. In Claude Code, run `/reload-plugins`. |
| A model schema is unavailable | Confirm the slug with `model list --output slugs`, then retry `model get-schema`. If the CLI is missing, use Docs MCP or [llms.txt](https://docs.modellix.ai/llms.txt). |
| `401 Unauthorized` | Set `MODELLIX_API_KEY`, or repair the saved profile with `modellix-cli auth login`, then verify with `doctor`. |
| `402 Payment Required` | Recharge in the [Modellix Console](https://www.modellix.ai/console/api-key) and retry. |
| A paid submission outcome is unknown | Run `modellix-cli task history` and check account activity before submitting again. |
| `task download` fails with a private or reserved network error | Local proxies sometimes map CDN hosts into `198.18.0.0/15`. Retry with `--allow-private-network` for trusted Modellix CDN hosts, or download the resource URL with `curl`. |
| `openclaw plugins update` does nothing | That command only refreshes npm-tracked installs. Reinstall from the original ClawHub, Git, or path source. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Skill" icon="wrench" href="/ways-to-use/skill">
    Install the Agent Skill on its own.
  </Card>

  <Card title="CLI" icon="terminal" href="/ways-to-use/cli">
    Learn the `modellix-cli` commands the plugin runs.
  </Card>

  <Card title="REST API" icon="code" href="/ways-to-use/api">
    Call Modellix directly without the CLI.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/get-started/pricing">
    Review model pricing before running paid tasks.
  </Card>
</CardGroup>