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

# Plugin

> Install the official Modellix Plugin in Claude Code, Codex, Cursor, OpenClaw, and other agent hosts so your coding agent can generate images and videos through the Modellix CLI or REST API.

The [Modellix Plugin](https://github.com/Modellix/modellix-plugin) packages everything your coding agent needs to generate images and videos 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.

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` and `model describe`, 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
```

Request-body schemas come from each model's documentation. Follow the `docs_url` returned by `model describe`, or the links in [llms.txt](https://docs.modellix.ai/llms.txt).

## 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 uses `model run --wait` or `task wait` instead of hand-written polling loops.
3. It never blindly retries a paid `model run` after an unknown submission outcome. It checks `modellix-cli task history` first.
4. It may use the helper scripts bundled in `skills/modellix/scripts/`, and falls back to plain CLI commands if a helper fails.
5. 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`.                                                     |
| `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>