media-gen — fal.ai cost-router

One fal.ai key covers every current image/video model, pay-per-use — no subscription, no monthly minimum. You prepay credit on fal.ai's dashboard and each request draws down from it: spend is real money — be surgical.

Auth

Read the key from the environment first; fall back to the hub's .env (the /jarvis-setup page's Media section writes it there). The hub itself resolves the same way the SessionStart hook does: JARVIS_HUB env var first, else the pointer file at ~/.jarvis-hub-path written by /jarvis-setup, else ~/jarvis-hub. Never hardcode a path to it and never echo/print/log the value:

hub="${JARVIS_HUB:-$(cat ~/.jarvis-hub-path 2>/dev/null)}"
hub="${hub:-$HOME/jarvis-hub}"
FAL_KEY="${FAL_KEY:-$(grep '^FAL_KEY=' "$hub/.env" 2>/dev/null | cut -d= -f2-)}"

If FAL_KEY is still empty after that, stop and tell the user to add it via /jarvis-setup — do not hunt for it elsewhere. Every request: header Authorization: Key $FAL_KEY.

Cost discipline (the point of this skill)

• Images are cheap (fractions of a cent). Iterate freely.
• Video bills per second. Default 3–5s, never more without an explicit ask. 5s vs 10s = real dollars. State the model + estimated cost BEFORE a video run and get the user's go-ahead unless they already gave one this session.
• Cheapest-fit routing: draft/test → FLUX schnell; final image → FLUX dev or nano-banana Pro; image→video → Kling (best value) before Seedance (pricier); upscale → Topaz only when the target actually needs it.
• No balance API — track spend at https://fal.ai/dashboard (billing page).

Model routing

Models rotate fast; slugs below verified 2026-07-14. When one 404s or a newer generation is out, search https://fal.ai/models?q=<term> (WebFetch) — new models work with the same key + call shape, no skill change.

Video model economics

Rough per-second cost comparisons circulating in the AI-video community as of Aug 2026 (credited to Rohit Mithe's "AI Creator Series" notes). These are one practitioner's numbers, not verified against fal's own billing page — treat them as a starting hypothesis for routing, and check the live price before a long job.

The routing consequence worth keeping: most everyday clips are a slow push-in on a still, which is the "no complex motion" case — so Kling stays the default and the expensive tiers are for shots with real camera movement or acting. Note the 720p ceiling on the best model: for a full-bleed website hero, resolution may matter more than motion quality, which flips the ranking.

Call shape

Sync (images, <60s):

curl -s -X POST "https://fal.run/<model-slug>" \
  -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"...", "image_size":"landscape_16_9", "num_images":1}'

Queue (video / long jobs): POST the same body to https://queue.fal.run/<model-slug> → response has status_url + response_url → poll status every ~10s until COMPLETED → GET response_url. Image→video body: {"prompt":"...", "image_url":"<https-url-or-data-uri>", "duration":"5"} (field names vary per model — on a 422, GET https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=<model-slug> for the exact schema).

Prompt rewriting (always do this)

The user gives a rough ask; rewrite before sending:

• Image: subject + style + lighting + composition + negative cues. A non-English ask → translate to an English prompt (models are English-tuned); NEVER put text in the image, especially non-Latin scripts.
• Photoreal image or any image→video first frame: build the prompt on a four-part cinematic formula — medium (photo/render/style) → content (subject + action) → frame (camera, lens, composition) → mood (lighting, palette, atmosphere) — naming the camera body, lens, lighting, and palette explicitly rather than leaving them implicit. Video bills per second, so a weak prompt costs real money on the reroll — this is where prompt quality has a price tag attached.
• Video: motion verbs + camera direction ("slow push-in", "orbit left"), one action per clip, explicit duration, "no audio" unless asked.
• Image→video: fix the input frame before you spend a second of video. The still constrains the clip more than the video model does — a weak frame on the best model is a weak clip, a strong frame on the cheapest model reads as footage. Iterating the still is nearly free; iterating the clip is billed per second. If the source image is soft, badly lit, or has no depth cue for the camera to move through, fix the still first — with whatever image tool is available (a separate image-generation skill, or media-gen's own image models above) — before spending on video. This is the single largest cost lever in this skill.

Outputs

fal URLs expire — download immediately:

mkdir -p ~/Downloads/media-gen && curl -s -o ~/Downloads/media-gen/$(date +%Y-%m-%d)-<slug>.<ext> "<result-url>"

Reply with the local path.

Boundaries

• Images for UI/illustration: if the user has a Gemini-based image skill installed separately (not bundled with this plugin), prefer it first for simple illustrations/UI graphics — it's usually cheaper. Reach for media-gen when a named fal.ai model, image→video, photoreal quality the other tool can't hit, or upscaling is actually needed.
• Commercial/client-facing use: fal outputs are commercially usable on paid credits, but check the specific model's terms page once per new model before shipping to a paying client.