--- name: modelflare-media description: Generate and edit images and generate videos with any image or video model on Modelflare through its OpenAI-compatible API. Use when the user asks to create, edit, upscale or animate pictures or videos, wants to compare media models or prices, or mentions Modelflare, Castaly or MODELFLARE_API_KEY. version: 1.0 metadata: generated_at: 2026-09-18T22:13:33Z source: https://modelflare.dev/skills/modelflare-media/SKILL.md image_models: 10 video_models: 27 --- # Modelflare Media Skill Modelflare is an API gateway that exposes image and video generation models behind one OpenAI-compatible base URL. This skill tells you how to pick a model, price a request, call the API correctly, wait for videos, and hand results back to the user. Text models are out of scope: use whatever model you already run on. ## Before the first call 1. The key lives in the environment variable `MODELFLARE_API_KEY`. Never print it, never write it into files, prompts or chat. If it is missing, ask the user to create one at https://modelflare.dev/keys and set it (macOS/Linux: `export MODELFLARE_API_KEY=...`; Windows PowerShell: `$env:MODELFLARE_API_KEY="..."`). Do not guess a key. 2. Base URL `https://modelflare.dev`. Every request carries `Authorization: Bearer $MODELFLARE_API_KEY`, `Content-Type: application/json` and `X-Modelflare-Skill: modelflare-media/1.0` (the last one lets the user's usage logs show this skill). 3. Use the bundled helper `scripts/mf.mjs`. It needs only Node 18+ (no bash, curl or jq) and behaves identically on macOS, Windows and Linux. Run it as `node scripts/mf.mjs ` from the skill directory, or with the absolute path to the script. Fall back to raw HTTP (see `references/api.md`) only when Node is unavailable. 4. Every successful call costs money from the user's wallet. One user intent means one request; never loop retries on generation failures, never batch without asking, and quote the estimate (`cost` command) before any video or any batch of more than one image. 5. Paths: write results under `./outputs/` in the current working directory unless the user names another folder; on Windows that is `.\outputs\`. Local reference files are read from disk and sent as data URLs; the gateway never reads the user's machine. ## Helper commands ```bash node scripts/mf.mjs models [--type image|video] [--max-usd N] [--group G] # live catalog with prices node scripts/mf.mjs cost --model M --size S --quality Q [--n N] # image estimate node scripts/mf.mjs cost --model M --seconds S --resolution R # video estimate node scripts/mf.mjs image --model M --prompt "..." [--size S] [--quality Q] [--n N] [--ref FILE|URL ...] [--out DIR] node scripts/mf.mjs video --model M --prompt "..." [--seconds S] [--resolution R] [--ref FILE|URL] [--out DIR] [--wait SECONDS] node scripts/mf.mjs task [--out DIR] # resume or download a video job node scripts/mf.mjs file # local file -> data URL ``` Add `--dry-run` to `image` or `video` to print the exact request (key redacted) without sending it. Use it when the user wants to review the call or when you are unsure about a parameter. ## Choose a model `references/models.md` is a snapshot of the catalog taken at 2026-09-18 22:13 UTC with a ready-to-send request template per model. Before choosing, run `node scripts/mf.mjs models` so prices and availability are current. Rules of thumb: image prices are USD per image for a given `size` and `quality`; video prices are USD per second for a given `resolution` (feature rows add modes such as image-to-video or audio, each with a minimum billed length). A model is callable only if one of its `enable_groups` is unlocked on the user's account; the default Modelflare key routes across unlocked groups automatically. If the API answers `model_unavailable` or a group error, pick another model from the same table instead of retrying. ## Generate an image ```bash node scripts/mf.mjs cost --model --size 1024x1024 --quality medium node scripts/mf.mjs image --model --prompt "a coastal observatory at dusk, film still" --size 1024x1024 --quality medium ``` The command prints the saved file paths as JSON. `size` and `quality` must be one of the pairs listed for that model; omit them to accept the model default. Raw form: `POST /v1/images/generations` with `{"model", "prompt", "n": 1, "size", "quality"}`; the response is `{"data": [{"url": ...} | {"b64_json": ...}]}`. ## Edit an image or use reference images Pass references with `--ref` (a local file, a public URL or a data URL; repeat for several). The helper picks the endpoint by model family: - `gpt-image*` models: `POST /v1/images/edits` with `"images": [ ... ]` (up to 4 references). - Every other image model: `POST /v1/images/generations` with `"image": ` (one reference). ## Generate a video ```bash node scripts/mf.mjs cost --model --seconds 5 --resolution 1080p node scripts/mf.mjs video --model --prompt "the kitten chases the butterfly across the meadow" --seconds 5 --resolution 1080p --ref ./start-frame.png ``` Videos are asynchronous: the helper submits to `POST /v1/videos`, prints the task id immediately, polls `GET /v1/videos/{task_id}` every 10 seconds, and downloads the MP4 when `status` is `succeeded`. If it stops before completion (wait limit, Ctrl+C, connection loss) the job is not lost: run `node scripts/mf.mjs task ` later. Pass a video file or URL as `--ref` for video-to-video models. ## Errors - `401`: the key is missing or wrong. Ask the user to check `MODELFLARE_API_KEY`. - `403` with code `insufficient_user_quota`: the wallet is empty. Point the user to https://modelflare.dev/topup and stop. - `429`: rate limited. Wait for `Retry-After` seconds once, then report if it repeats. - `model_unavailable`, `unsupported_endpoint` or a group error: choose another model from the catalog; do not change the key. - Any other `4xx`/`5xx` or a failed video task: show the user the returned message and request id. Do not resubmit automatically. ## After the call Report the saved file paths, the model used and the estimate from `cost`. The exact charge appears in the user's usage logs at https://modelflare.dev/usage-logs. ## Package contents - `references/models.md`: image and video models with sizes, resolutions, references, USD prices and a request template each. - `references/api.md`: request and response shapes for the image and video endpoints. - `scripts/mf.mjs`: the Node helper used above (models, cost, image, video, task, file). Latest version: https://modelflare.dev/skills/modelflare-media/SKILL.md. Reinstall with `curl -fsSL https://modelflare.dev/skills/modelflare-media/install.sh | sh` (macOS/Linux) or `irm https://modelflare.dev/skills/modelflare-media/install.ps1 | iex` (Windows PowerShell).