Skip to main content
The Modellix Plugin gives a coding agent twelve skills for planning and generating images, videos, and speech with Modellix. A plugin install also includes host rules, slash commands, spend-safety hooks, and three MCP servers. The repository follows the Agent Plugins 1.0.0 specification: root plugin.json is the portable manifest, skills/ is the skill location, and root mcp.json declares the MCP servers. Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, and Hermes use host adapters on that core. For a visual Excalidraw workspace with image prepare/confirm, HTML drafts, and presentations, see Agent Canvas.

Plugin or Skill

Skill-only install steps are on the Skill page. npx skills add can install modellix-design or modellix-image-prompt-engineering on its own. The other skills ship with the plugin and with a checkout of this repository.

Skills

Planning skills write prompts and stop there. They hand generation to modellix-design. They do not choose a model, authenticate, or submit a task. modellix-ffmpeg and modellix-moviepy do not call Modellix and do not read MODELLIX_API_KEY. Each skill has a check script that reports whether the local tool is usable and prints an install command. The script does not install FFmpeg, moviepy, or Pillow.
Run the check before the first ffmpeg command or moviepy import. When ok is false, the agent shows install_command and waits for you to confirm.

Requirements

  • Prompt preparation needs no credential. Generation needs a Modellix API key from the Modellix Console, or a saved CLI profile.
  • modellix-cli 0.0.11 or later on Node.js 18.17 or later. Preflight installs or refreshes it from the public npm latest tag before the first paid CLI command.
  • Python 3.10 or later for preflight and optional hooks. Direct CLI and REST calls still work when Python is unavailable.
  • FFmpeg (ffmpeg and ffprobe, with libx264 and aac) only for modellix-ffmpeg.
  • moviepy 2.x and Pillow only for modellix-moviepy.
Preflight compares the installed CLI with npm latest, upgrades only to a newer exact version, then runs doctor. A registry or install failure keeps a working CLI. If no CLI is usable and MODELLIX_API_KEY is set, it recommends REST. Set MODELLIX_CLI_AUTO_UPDATE=0 when an environment must keep its current CLI version.

Install as a Plugin

The public npm package @modellix/modellix-plugin contains the portable plugin. For Cursor, the installer copies it into the local plugin directory:
Update an npm-installed local plugin. The previous directory is kept as a backup:
For another host, materialize a versioned bundle and point that host’s local plugin flow at the directory:
Plain npm install @modellix/modellix-plugin only downloads the package into node_modules. It does not register the plugin with a host. Pi and OpenClaw can install the npm package through their own installers, shown in the tabs below.

Install as a Skill

When you want one skill without the rest of the plugin, install it from skills.sh:
modellix-design runs generation. modellix-image-prompt-engineering only prepares image prompts and hands generation back to modellix-design. Installing modellix-design alone does not include the other skills. The Skill guide covers Cursor, OpenCode, Pi, and Hermes installs.

Configure Your API Key

Generation and authenticated CLI or REST calls read the same credential. Prompt-only skills do not.
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.
  • In Cursor, you can set the key as the MODELLIX_API_KEY plugin variable for CLI and REST calls.
  • In Hermes, prefer ~/.hermes/.env or the session environment.
The plugin declares three MCP servers and does not put an API key in the manifests: The Cursor MODELLIX_API_KEY variable does not automatically become the Bearer header for Media Generation or Web Tools. See Media Generation, Docs Search, and Web Tools.
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 provider/model slug yourself. The plugin does not substitute one.
1

Check the CLI and Credentials

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

Ask Your Agent to Generate Something

If Media Generation tools are available, the plugin submits once through that server. Otherwise it uses the CLI, waits for the task, and downloads the result.
3

Confirm the Output

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

Supported Task Types

Model Selection

You name the provider/model slug. If you leave it out, the agent asks which model to run and waits. It does not pick a slug from a built-in list.
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). On the Media Generation path the agent calls modellix_get_schema with the same slug. See the CLI schema command. If neither the CLI nor Media Generation is available, the plugin uses Docs Search when connected, then docs_url from model describe, or the model page in llms.txt. The Skill guide covers when the agent fetches the schema.

How the Plugin Runs Tasks

  1. When Media Generation tools are available and the input is not a local file, it submits once with modellix_submit_task.
  2. Otherwise it runs skills/modellix-design/scripts/preflight.py before the first CLI command, then modellix-cli model run --wait and task download.
  3. It uses the REST API only when Media Generation and the CLI are both unavailable.
  4. It reads the request schema before a non-trivial submit, and skips that call when you already supplied a complete body.
  5. It uses modellix_wait_task, model run --wait, or task wait instead of a hand-written polling loop.
  6. It does not retry a paid submit after an unknown outcome, and it does not start a second path for the same request. It checks modellix_get_task or modellix-cli task history first.
  7. It may use the helpers in skills/modellix-design/scripts/. If a helper fails, it falls back to plain CLI commands.
  8. It treats modellix-cli --help and the npm package as the source of truth for CLI flags.
Resource URLs expire in about 7 days. Download results before they expire.

Slash Commands

Hosts that load the packaged commands expose sixteen shortcuts. Each command routes to a skill and adds no separate runtime. Pi, Hermes, and OpenCode ignore commands/. The planning commands and the paid commands image, video, and audio set disable-model-invocation: true, so only you can trigger them. doctor, models, tasks, and download stay available to the agent.

Hooks

Hosts that load the packaged hook adapters run lightweight guards. Hooks never submit, poll, or download on their own. Pi, Hermes, OpenCode, and Codex ignore hooks/. Hook logic fails open. Session state stores command fingerprints, model slugs, and task IDs. It does not store prompts, request bodies, or API keys.

Troubleshooting

Next Steps

Skill

Install modellix-design or the image prompt skill on its own.

CLI

Learn the modellix-cli commands the plugin runs.

REST API

Call Modellix directly without the CLI.

Media Generation

Submit image, video, and speech tasks when the plugin’s Media Generation tools are available.

Docs Search

Search these docs from the plugin’s Docs Search server.

Web Tools

Search the public web and fetch public URLs.

Pricing

Review model pricing before running paid tasks.