Plugin

The Modellix Plugin packages everything your coding agent needs to generate images and videos with Modellix: 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 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

If you only need the Agent Skill, see the Skill guide, which covers the standalone modellix-skill repository as well.

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
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
Recommended: modellix-cli on Node.js 18.17 or later

npm install --global modellix-cli@latest
modellix-cli doctor --json

The plugin works without the CLI by calling the REST API directly, but the CLI gives your agent faster task submission, built-in waiting, and safer downloads.

Install as a plugin

Claude Code
Codex
Cursor
OpenClaw
Pi

Install:

/plugin marketplace add Modellix/modellix-plugin
/plugin install modellix@modellix

Update:

/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:

claude --plugin-dir /path/to/modellix-plugin
claude plugin validate /path/to/modellix-plugin

Add the marketplace, then install modellix from the /plugins list:

codex plugin marketplace add Modellix/modellix-plugin

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

Browse or submit the plugin through cursor.directory using the repository URL https://github.com/Modellix/modellix-plugin.To install from a local clone:

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:

git -C ~/.cursor/plugins/local/modellix pull

Reload the window again after pulling.

The ClawHub package @modellix/modellix-plugin ships the Open Plugins layout as a content and skill bundle, not a TypeScript runtime plugin.

openclaw plugins install clawhub:@modellix/modellix-plugin

Install from a local checkout or Git instead:

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.

Pi loads the repository as a Pi package that contributes skills only.

pi install git:github.com/Modellix/modellix-plugin

Local checkouts work too:

pi install /path/to/modellix-plugin

Update:

pi update --extensions

Install as a skill

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

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

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

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.

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.

Verify the install

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

Check the CLI and credentials

modellix-cli doctor --json

doctor reports the Node.js version, the API-key source, API connectivity, and your team balance without printing the key.

Ask your agent to generate something

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.

Confirm the output

The agent downloads results into your working directory. To reproduce the same flow manually:

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

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:

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.

How the plugin runs tasks

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

It prefers the CLI when installed, and falls back to the REST API otherwise.
It uses model run --wait or task wait instead of hand-written polling loops.
It never blindly retries a paid model run after an unknown submission outcome. It checks modellix-cli task history first.
It may use the helper scripts bundled in skills/modellix/scripts/, and falls back to plain CLI commands if a helper fails.
It treats modellix-cli --help and the npm package 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 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

Skill

Install the Agent Skill on its own.

CLI

Learn the modellix-cli commands the plugin runs.

REST API

Call Modellix directly without the CLI.

Pricing

Review model pricing before running paid tasks.

Getting Started

Ways to Use

Plugin or skill

What the plugin provides

Requirements

Install as a plugin

Install as a skill

Configure your API key

Verify the install

Supported task types

Default models

How the plugin runs tasks

Troubleshooting

Next steps

Skill

CLI

REST API

Pricing

​Plugin or skill

​What the plugin provides

​Requirements

​Install as a plugin

​Install as a skill

​Configure your API key

​Verify the install

​Supported task types

​Default models

​How the plugin runs tasks

​Troubleshooting

​Next steps

Skill

CLI

REST API

Pricing

Plugin or skill

What the plugin provides

Requirements

Install as a plugin

Install as a skill

Configure your API key

Verify the install

Supported task types

Default models

How the plugin runs tasks

Troubleshooting

Next steps