如何透過 Modelflare 在 Claude Code 中用一句話生成圖像和影片

How to give Claude Code image and video generation with the Modelflare Claude Code plugin, the Media Skill, or the @modelflare/mcp-server MCP server, all on one Smart API Key.

Claude Code is good at writing the landing page. It is not good at producing the hero image for that page, the 5-second product loop in the header, or the twelve icon variants the designer asked for. Those normally mean leaving the terminal: open an image tool, sign in to a video provider, download files, rename them, drag them into public/, and come back.

The friction is not the generation itself. It is everything around it:

• Every media provider has its own contract. OpenAI-compatible image models use POST /v1/images/generations; Gemini image models use native generateContent. Sending a model to the wrong endpoint is rejected with unsupported_endpoint (Image models).
• Video is asynchronous. You create a task, poll it, and download the result before the URL expires.
• Prices change. "Which video model under 0.10 USD per second can do image-to-video?" is a question you should not answer from memory.
• Keys multiply. A separate key per vendor means separate billing, separate quotas, and separate places to leak a secret.

This guide removes that loop. By the end, a single sentence in Claude Code produces a file on disk.

Three ways in, one key

There are three Modelflare integrations that reach Claude Code. They overlap on purpose, so pick the one that matches how you work.

All three use the same credential: a Modelflare Smart API Key in the MODELFLARE_API_KEY environment variable.

Step 1: Create a Smart API Key

An ordinary Modelflare key is bound to one routing group and can only call the models that group serves. A Smart API Key is bound to auto: it can call every model your account has access to and resolves the routing group per request. For media work this matters, because image and video models are rarely all served by the same group.

1. Sign up or open the console.
2. Go to API Keys and choose Create Smart API Key.
3. Pick a routing strategy: Balanced (default), Stability first, or Low price first. You can change it on the existing key later; the next request uses the new order.

A request is billed with the multiplier of the group that actually served it, and the consume log records the resolved group and strategy (Usage and cost).

Then expose the key to the environment Claude Code runs in:

# macOS / Linux: add this to your shell profile to keep it
export MODELFLARE_API_KEY="sk-..."

# Windows PowerShell: the second line makes it persistent
$env:MODELFLARE_API_KEY = "sk-..."
setx MODELFLARE_API_KEY "sk-..."

The Media Skill never writes the key into files or prompts and never prints it. Keep it that way on your side: do not paste it into a chat, a commit, or a ticket.

If Claude Code itself does not run through Modelflare yet and you want it to, the Claude Code setup guide covers the installer (curl -fsSL https://modelflare.dev/install/claude.sh | sh) and the manual ~/.claude/settings.json. That is optional: media generation works whatever model Claude Code is using for text.

Step 2a: Install the Claude Code plugin (recommended)

The plugin is a Claude Code marketplace hosted on GitHub. Two commands install it:

claude plugin marketplace add castaly-ai/modelflare-claude-code
claude plugin install modelflare@modelflare

Both commands print a confirmation (✔ Successfully added marketplace: modelflare and ✔ Successfully installed plugin: modelflare@modelflare (scope: user)). The plugin carries the modelflare-media skill, so after installing there is nothing else to configure besides MODELFLARE_API_KEY. To pick up a newer version later:

claude plugin update modelflare@modelflare

Step 2b: Or install the Media Skill directly

If you would rather not use the plugin system, or you also want the skill in Codex, the docs offer an install that works for any agent. The simplest version is to ask the agent itself:

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.

Or place the files yourself:

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

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

Both install into ~/.claude/skills/modelflare-media, which Claude Code reads as a user-level skill. A project-level copy goes into .claude/skills/ inside the repository. For Codex, set SKILL_DIR first:

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

The helper script needs only Node.js 18 or newer. You can read the SKILL.md before installing to see exactly what the agent will follow.

Install either the plugin or the standalone skill, not both, so Claude Code does not see two copies of the same skill.

Step 2c: Or add the MCP server

The MCP server exposes media generation as explicit tools. Its README gives this client configuration:

{
  "mcpServers": {
    "modelflare": {
      "command": "npx",
      "args": ["-y", "@modelflare/mcp-server"],
      "env": {
        "MODELFLARE_API_KEY": "<your Smart API Key>"
      }
    }
  }
}

In Claude Code you can put that block in a project .mcp.json, or register it from the terminal with Claude Code's own claude mcp add command:

claude mcp add --env MODELFLARE_API_KEY="$MODELFLARE_API_KEY" \
  --transport stdio modelflare -- npx -y @modelflare/mcp-server

Claude Code confirms the registration and health-checks the server:

$ claude mcp add --env MODELFLARE_API_KEY="$MODELFLARE_API_KEY" \
    --transport stdio modelflare -- npx -y @modelflare/mcp-server
Added stdio MCP server modelflare with command: npx -y @modelflare/mcp-server to local config

$ claude mcp list
Checking MCP server health…

modelflare: npx -y @modelflare/mcp-server - ✔ Connected

By default this is a local-scope entry, private to you in the current project. Remove it with claude mcp remove modelflare -s local.

The npm package (current version 0.1.1) declares node >=20.3. It reads four environment variables:

For Claude Desktop, the GitHub releases include a modelflare-mcp-<version>.mcpb bundle that asks for the key, base URL and output folder on open.

Worked example: a hero image and a looping header video

Here is the workflow we use for a small product landing page, with Claude Code started in the project root and the plugin installed. Under it is a real run of the MCP tool behind prompt 1.

Prompt 1:

Generate a 16:9 poster of a coastal observatory at dusk with gpt-image-2 and save it to public/hero.png.

With the skill, Claude Code reads SKILL.md, fetches the live catalog from https://modelflare.dev/api/pricing to confirm the key can use gpt-image-2 and what it costs, opens the gpt-image-2 model page for the exact request body and limits, and calls POST /v1/images/generations with its own HTTP client. Every call carries the header X-Modelflare-Skill: modelflare-media/1.0, so you can filter those requests in the usage logs.

With the MCP server, the same sentence becomes a generate_image tool call. Model-specific fields go in parameters and are sent unchanged, and the result is saved immediately because result URLs expire. Here is a real generate_image call from our test run, at the cheapest quality setting the gpt-image-2 page documents:

tool: generate_image
arguments:
  model: gpt-image-2
  prompt: A 16:9 poster of a coastal observatory at dusk, flat illustration
  parameters: { "size": "1536x1024", "quality": "low" }

result:
  Saved 1 image(s):
  ./modelflare-output/gpt-image-2-2026-10-14T14-22-22-789Z.png

It took about 35 seconds and produced a 1.9 MB PNG. list_models on the same key returned image and video models, each with its docs URL:

[
  { "id": "gpt-image-2", "kind": "image", "docs": "https://docs.modelflare.dev/models/image/gpt-image-2/" },
  { "id": "seedance-2.0-fast", "kind": "video", "docs": "https://docs.modelflare.dev/models/video/seedance-2-0-fast/" },
  { "id": "wan2.7-image", "kind": "image", "docs": "https://docs.modelflare.dev/models/image/wan2-7-image/" }
]

(Trimmed to three entries; the full list follows your account's access.)

If the upstream is briefly unavailable, the tool returns the error with a request ID rather than failing silently. On our first attempt we got exactly that, and the retry a minute later succeeded. Quote the request ID if you contact support.

Prompt 2:

Turn public/hero.png into a 5 second 1080p video with Seedance and save it as public/hero-loop.mp4.

Video is asynchronous. With the MCP server you can watch the three steps happen: create_video starts the task and returns its ID, get_video_status reports progress, and download_video saves the finished file (it can wait up to 300 seconds first). With the skill, Claude Code performs the same create-poll-save cycle itself, using the contract from the model page, for example seedance-2.0 or seedance-2.0-fast.

The local start frame is embedded in the request as a data URL. The skill does not upload files to any storage, so keep reference images small (a few MB).

Prompt 3, before committing to a model:

Which video models under 0.10 USD per second can do image-to-video? Show the price per 5-second clip.

Because the catalog is read live, the answer reflects today's prices and today's models, not what was true when the skill was installed.

Tips

Name the model when it matters. "With gpt-image-2" or "with Seedance" pins the choice. Leave it out and the agent picks from what your key can reach, which is fine for drafts but makes results harder to reproduce. Use exact IDs from Models & Pricing; the docs list 14 image models and 28 video models.

Ask for a quote first on video. Video is billed per second or per token depending on the model (see the video models table). A one-line "quote this before running it" saves surprises.

Keep output out of git by default. The MCP server writes to ./modelflare-output unless you set MODELFLARE_OUTPUT_DIR. Add that folder to .gitignore and move only the assets you keep into public/.

Reproduce work from the browser. Every generation in the Castaly workbench has a "Reproduce this in your own agent" panel with the install message and a task brief. Paste the brief into Claude Code and it repeats the same model and parameters against your key.

Read errors literally.

• 401: the key is missing or invalid. Create a Smart API Key at modelflare.dev/keys.
• model_not_found / model_unavailable: a regular key only calls its own group's models. With a Smart API Key, the model is not available to your account right now. The skill cannot unlock model groups.
• 403 insufficient_user_quota: top up at modelflare.dev/billing.
• unsupported_endpoint: the request went to the wrong contract (for example, a Gemini image model sent to /v1/images/generations).

Know what the skill does not do. It does not decide retries, batching or what to report back; that is between you and your agent. It only documents the API.

Where to go next

• Media Skill guide: docs.modelflare.dev/guides/clients/media-skill
• Claude Code setup: docs.modelflare.dev/guides/clients/claude-code
• Smart API Key: docs.modelflare.dev/guides/features/smart-api-key
• Image models: docs.modelflare.dev/models/image · Video models: docs.modelflare.dev/models/video
• Claude Code plugin: github.com/castaly-ai/modelflare-claude-code
• MCP server: npmjs.com/package/@modelflare/mcp-server · github.com/castaly-ai/modelflare-mcp

The point is not that Claude Code can now draw. It is that the asset step stops being a context switch: one key, one sentence, one file in the place your code expects it.

Disclosure: I'm part of the Modelflare team, which builds the AI API gateway mentioned in this article.