Modellix Plugin for Coding Agents

The Modellix Plugin packages what a coding agent needs to generate images, videos, and speech audio with Modellix: six skills, Media Generation MCP, Docs Search, credential handling, and retry rules that match the CLI exit codes. You name the provider/model slug. When the prompt leaves the model unnamed, the agent asks which slug to run and waits. For a visual Excalidraw workspace with image prepare/confirm, HTML drafts, and presentations, see Agent Canvas instead. The repository follows Agent Plugins 1.0.0, with portable skills and adapters for Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, and Hermes. Root mcp.json declares Modellix Docs Search at https://docs.modellix.ai/mcp and Modellix Media Generation at https://tool.modellix.ai/mcp/media. The manifests contain the URLs only.

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, both MCP servers, and six skills under `skills/`	Your host has a plugin marketplace (Claude Code, Codex, Cursor, OpenClaw, Pi)
Skill	One skill folder, such as `skills/modellix-design`	Your host has no plugin marketplace, or you only want that skill

A skill-only install of modellix-design includes execution. It does not include the prompt-planning or local-edit skills. See the Skill guide for per-skill installs.

What the Plugin Provides

Media Generation MCP when its tools are available and the input is a prompt or public URL: modellix_get_schema, then one modellix_submit_task, then modellix_wait_task
The CLI when Media Generation is unavailable, the input is a local file, or the task is a batch or download: preflight when that path is selected, then modellix-cli doctor, model run --wait, and task download
REST only when Media Generation and the CLI are both unavailable
A question for the provider/model slug when you do not name one
Model discovery through modellix_list_models and modellix_get_schema, or modellix-cli model list, model describe, and model get-schema, 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

Hosts that load plugin commands can run /modellix:prompt, /modellix:social-card, /modellix:infographic, /modellix:image, /modellix:video, /modellix:audio, /modellix:doctor, /modellix:models, /modellix:tasks, and /modellix:download. On Cursor, a repeated modellix_submit_task for a model slug already submitted in the session asks for confirmation first.

Skills in the Plugin

modellix-design runs generation. modellix-image-prompt-engineering writes an image prompt and leaves the model choice to you. The four skills below plan prompts or edit files that are already on disk. Prompt-planning skills pass generation to modellix-design when you want a new asset. None of the four submits a paid task.

Skill	Role
`modellix-social-card`	Writes one prompt per social placement, with aspect ratio and on-image text. It covers mainstream network covers, thumbnails, and carousels.
`modellix-infographic`	Turns a source into one infographic prompt, quotes the source facts, and confirms the structure before the prompt is ready.
`modellix-ffmpeg`	Concatenates, trims, reframes, transcodes, and burns subtitle files for media already on disk. `scripts/check_ffmpeg.py --json` reports whether FFmpeg is usable and prints a platform install command. You install FFmpeg yourself.
`modellix-moviepy`	Builds titles, lower thirds, and a timed stack of clips and voiceover for files already on disk. `scripts/check_moviepy.py --json` reports whether moviepy 2.x and Pillow import, and prints a pip command. You install those packages yourself.

modellix-social-card, modellix-infographic, modellix-ffmpeg, and modellix-moviepy ship with the plugin and with a checkout of the repository. They are separate from the Smithery and ClawHub listing for modellix-design.

Requirements

A Modellix API key from the Modellix Console
Recommended: modellix-cli on Node.js 18.17 or later
Python 3.10 or later when you want automatic CLI preflight. Media Generation, direct CLI, and REST use remain available without Python

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

On the CLI path, skills/modellix-design/scripts/preflight.py checks public npm latest and, when that version is newer, installs that exact CLI version before execution. Set MODELLIX_CLI_AUTO_UPDATE=0 when the environment must keep its installed CLI. A registry or install failure keeps a working CLI. When no CLI is usable and MODELLIX_API_KEY is set, preflight recommends REST. The plugin still runs when the CLI is absent: Media Generation MCP when that server is connected, and the REST API when both Media Generation and the CLI are unavailable. The CLI adds local-file uploads, batch, built-in waiting, and safer downloads.

Install as a Plugin

The published npm package @modellix/modellix-plugin is 4.2.2. That package still uses the CLI-first workflow and built-in default models. GitHub marketplace installs, git checkouts, and npx skills add from https://github.com/Modellix/modellix-plugin install 4.7.0.

For an npm installation into Cursor, run:

npx --yes @modellix/modellix-plugin@4.2.2 install --host cursor

Use --force to update an existing installation while retaining its previous directory as a backup. To materialize the complete bundle for another compatible host, use install --host portable --target ./modellix-plugin and open that directory through the host’s local plugin flow. Plain npm install downloads the package without registering it in every host. The command above is pinned to 4.2.2, so --force and install --host portable install that same package.

Claude Code
Codex
Cursor
OpenClaw
Pi

Install from the GitHub repository (4.7.0):

/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. This install follows the GitHub repository (4.7.0):

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 (4.7.0 on current main):

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 npm command at the top of this section installs 4.2.2.

The ClawHub package @modellix/modellix-plugin ships the Open Plugins layout as a content and skill bundle, not a TypeScript runtime plugin.The npm source installs the published package (4.2.2):

openclaw plugins install npm:@modellix/modellix-plugin

A git or local checkout follows the repository (4.7.0). ClawHub is a separate listing:

openclaw plugins install clawhub:@modellix/modellix-plugin
openclaw plugins install .
openclaw plugins install git:github.com/Modellix/modellix-plugin

Update an npm install with:

openclaw plugins update npm:@modellix/modellix-plugin

For a ClawHub, Git, or path install, reinstall from that same source. openclaw plugins update only refreshes npm-tracked installs.

Pi loads the repository as a Pi package that contributes skills only.The npm source installs the published package (4.2.2):

pi install npm:@modellix/modellix-plugin

Git and local checkouts follow the repository (4.7.0):

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

Update:

pi update --extensions
pi update npm:@modellix/modellix-plugin

Install as a Skill

When your host has no plugin marketplace, or you want one skill, install it from the GitHub repository (4.7.0):

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-image-prompt-engineering

modellix-design executes image, video, and audio workflows. modellix-image-prompt-engineering prepares image prompts. The Skill guide covers skill installs for skills.sh, ClawHub, OpenCode, Cursor, Pi, Hermes, and Smithery, and explains which skills are plugin-only.

Configure Your API Key

Every install shape reads the same credential for CLI and REST.

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 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.
Media Generation expects the host to attach Authorization: Bearer to https://tool.modellix.ai/mcp/media. Use the host’s secret store. The plugin manifests declare the URL only.
In Cursor, the MODELLIX_API_KEY plugin variable covers the CLI and REST paths. It does not become the Media Generation Authorization header.
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. Name the model in the prompt.

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. The Media Generation path uses the host’s Authorization header and does not run this check first.

Ask Your Agent to Generate Something

Generate an image of a cinematic sunset over a futuristic city skyline with google/nano-banana-2-lite.

google/nano-banana-2-lite in that prompt is a slug you chose. When you omit the slug, the agent asks which model to run. With Media Generation connected and a prompt or public URL as input, it submits through that MCP server and waits for the task. It uses the CLI when that path is unavailable, and REST when the CLI is unavailable too.

Confirm the Output

The agent saves results before they expire (about 7 days). To reproduce the CLI path 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
`text-to-speech`	Synthesize speech from text and a voice in that model’s schema
`speech-to-text`	Transcribe a public audio URL
`speech-to-speech`	Synthesize speech from a reference clip and text, using the fields that slug requires

Exact request bodies come from modellix_get_schema or modellix-cli model get-schema. The Skill guide lists the required fields.

Name a Model

The plugin uses the provider/model slug you name. When you leave it unnamed, the agent asks and waits. Listing models shows options. It does not authorize a submit, and the agent does not pick a slug from that list for you.

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

On the Media Generation path, the same lookups are modellix_list_models and modellix_get_schema. modellix_get_schema is public and does not need an API key. JSON is the default for model get-schema. See the CLI schema command and Media Generation MCP. The agent reads the schema before a non-trivial submit. It skips that call when you already supplied a complete body. If neither Media Generation nor the CLI can provide the schema, it uses Docs Search when connected, then docs_url from model describe, or the model page in llms.txt.

Model slugs are exact, and decimals matter. Copy the slug from model list or the model page.

How the Plugin Runs Tasks

It uses Media Generation MCP when modellix_submit_task is available and the input is a prompt or public URL. A local file, a protocol error, or 401 leaves this path. Those outcomes are reasons to switch paths, and the agent does not retry the same MCP call.
It uses the CLI after scripts/preflight.py --json when that path is selected and Python is available. Preflight may install a newer exact CLI from public npm latest. Local files, batch, task download, and the private-network CDN fallback use the CLI.
It uses the REST API only when the Media Generation tools are absent and the CLI is unavailable.
It reads the request schema with modellix_get_schema or model get-schema before a non-trivial submit, and skips that call when you already supplied a complete body.
It uses modellix_wait_task, model run --wait, or task wait instead of a hand-written polling loop. A Media Generation deadline with data.wait.timed_out=true is a snapshot. The agent waits again with the same task ID.
It does not submit the same paid request again after an unknown outcome. submission_unknown, or a connection drop before a trustworthy response, does not start model run or a REST POST for that request. When a task ID came back, it continues with modellix_get_task or modellix_wait_task. When no ID came back, it checks modellix-cli task history first.
Its REST fallback rejects redirects on authenticated requests, bounds response reads by the remaining deadline, and preserves known task IDs on timeout.
It may use the helper scripts bundled in skills/modellix-design/scripts/, and falls back to plain CLI commands if a helper fails.
On Cursor, it asks before a repeated modellix_submit_task for a model slug already submitted in the session.
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`.
The agent picks a model without asking	The npm package is still 4.2.2 and includes built-in defaults. Install 4.7.0 from the GitHub repository, a marketplace, or `npx skills add`.
A model schema is unavailable	Confirm the slug with `modellix_list_models` or `model list --output slugs`, then retry `modellix_get_schema` or `model get-schema`. If both are missing, use Docs Search or llms.txt.
`401 Unauthorized`	On the CLI or REST path, set `MODELLIX_API_KEY` or repair the saved profile with `modellix-cli auth login`, then verify with `doctor`. On the Media Generation path, attach `Authorization: Bearer` in the host MCP config. A `401` there means this host cannot use that server, so switch to the CLI.
`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. If Media Generation returned `submission_unknown`, do not start a CLI or REST submit for the same request.
`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. For npm, run `openclaw plugins update npm:@modellix/modellix-plugin`. For ClawHub, Git, or a path install, reinstall from that source.

Next Steps

Skill

Install one Agent Skill on its own.

Media Generation MCP

See the tools the plugin calls when Media Generation is connected.

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

Team

Modellix Plugin for Coding Agents

Plugin or Skill

What the Plugin Provides

Skills in the Plugin

Requirements

Install as a Plugin

Install as a Skill

Configure Your API Key

Verify the Install

Supported Task Types

Name a Model

How the Plugin Runs Tasks

Troubleshooting

Next Steps

Skill

Media Generation MCP

CLI

REST API

Pricing

​Plugin or Skill

​What the Plugin Provides

​Skills in the Plugin

​Requirements

​Install as a Plugin

​Install as a Skill

​Configure Your API Key

​Verify the Install

​Supported Task Types

​Name a Model

​How the Plugin Runs Tasks

​Troubleshooting

​Next Steps

Skill

Media Generation MCP

CLI

REST API

Pricing

Plugin or Skill

What the Plugin Provides

Skills in the Plugin

Requirements

Install as a Plugin

Install as a Skill

Configure Your API Key

Verify the Install

Supported Task Types

Name a Model

How the Plugin Runs Tasks

Troubleshooting

Next Steps