Modelflare Media Skill for agents

The Modelflare Media Skill is an installable agent skill: a folder with a SKILL.md, a generated model reference and two helper scripts. Once it is in your agent's skills directory, Claude Code, Codex or any agent that reads SKILL.md knows how to choose a Modelflare image or video model, quote its price, send the right request, wait for videos and save the result.

The package is generated from the live model catalog every few minutes, so the model list and prices in it never go stale. Text models are intentionally out of scope: your agent already has one. The helper script needs only Node.js 18 or newer, which Claude Code and Codex already require, and behaves the same on macOS, Windows and Linux.

1. Install

You do not need to know where your agent keeps skills; the agent does. Send it this message, the same one for every agent:

Install this skill: https://modelflare.dev/skills/modelflare-media/modelflare-media.zip (or use the attached zip), then read its SKILL.md. If you do not support skills, extract it anywhere and follow SKILL.md. My key is in the environment variable MODELFLARE_API_KEY.

If the agent cannot download files, download the zip yourself and attach it to the message. Agents that support skills (Claude Code, Codex and others) install it in their own skills location; an agent without a skills mechanism can still read SKILL.md and run scripts/mf.mjs from wherever it extracted the package.

Manual install (optional)

Only needed if you prefer to place the files yourself, for example on a shared machine or in CI. macOS and Linux:

curl -fsSL https://modelflare.dev/skills/modelflare-media/install.sh | sh

Windows PowerShell:

irm https://modelflare.dev/skills/modelflare-media/install.ps1 | iex

Both install into ~/.claude/skills/modelflare-media (on Windows that is %USERPROFILE%.claude\skills), which Claude Code reads as a user-level skill; a project-level copy goes into .claude/skills/ inside the repository. For another agent, set SKILL_DIR to its skills folder first (check that agent's documentation for the exact path):

SKILL_DIR=~/.codex/skills curl -fsSL https://modelflare.dev/skills/modelflare-media/install.sh | sh

$env:SKILL_DIR = "$HOME\.codex\skills"; irm https://modelflare.dev/skills/modelflare-media/install.ps1 | iex

You can also read SKILL.md directly to see what the agent will follow.

2. Give your agent a key

Create an API key in the console and set it in the environment your agent runs in. macOS and Linux (add it to your shell profile to keep it):

export MODELFLARE_API_KEY="sk-..."

Windows PowerShell, for the current window or persistently:

$env:MODELFLARE_API_KEY = "sk-..."
setx MODELFLARE_API_KEY "sk-..."

The skill never writes the key into files or prompts and never prints it. Accounts created through Castaly already have a key named Castaly that routes across every unlocked group; any other key with image or video groups works too.

3. Ask for media

Talk to your agent as usual:

• "Generate a 16:9 poster of a coastal observatory at dusk with gpt-image-2."
• "Turn this start frame into a 5 second 1080p video with Seedance."
• "Which video models under 0.10 USD per second can do image-to-video?"

The agent reads references/models.md for sizes, resolutions, reference limits, prices and a request template per model, runs node scripts/mf.mjs models for the live numbers and cost for an estimate, then image or video to generate. Local reference files are converted to data URLs automatically. Results land in ./outputs/ (.\outputs</code> on Windows). Every call carries the header X-Modelflare-Skill: modelflare-media/1.0, so the usage logs show which requests came from the skill.

4. From the Castaly workbench

Every generation in the Castaly workbench has a "Reproduce this in your own agent" panel with the install message, the zip and a task brief. Send the install message once, then paste the brief, and the agent reproduces the same model and parameters against your own key.

What the skill does not do

• It never retries a failed generation on its own and never batches without asking; each user request becomes one billable call.
• It does not upload files to any storage: local reference images are embedded in the request as data URLs, so keep them small (a few MB).
• It cannot unlock model groups. If the API answers model_unavailable, the agent proposes another model from the same table.

Package layout

modelflare-media/
  SKILL.md                 when to use, rules, endpoints, errors
  references/models.md     image and video models with USD prices and request templates
  references/api.md        request and response shapes
  scripts/mf.mjs           Node 18+ helper: models, cost, image, video, task, file

Reinstall at any time to pick up new models; both installers replace the folder in place.