@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/fluidsim/scripts/solver_config_validator.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Validate a bounded FluidSim 0.9 JSON simulation plan."""
+
+from __future__ import annotations
+
+import argparse
+
+try:
+    from ._common import ToolError, checked_input, emit_json, fail_json, load_json
+    from ._schema import example_config, validate_config
+except ImportError:  # Direct script execution.
+    from _common import ToolError, checked_input, emit_json, fail_json, load_json
+    from _schema import example_config, validate_config
+
+
+TOOL = "fluidsim-solver-config-validator"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Validate strict local JSON against the static FluidSim 0.9 CFD "
+            "configuration profile. No FluidSim package is imported and nothing runs."
+        )
+    )
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--config", help="Configuration JSON within --root.")
+    source.add_argument(
+        "--example",
+        action="store_true",
+        help="Emit a bounded example configuration as strict JSON.",
+    )
+    parser.add_argument(
+        "--root",
+        default=".",
+        help="Local I/O boundary (default: current directory).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.example:
+            emit_json(example_config())
+            return 0
+        path = checked_input(
+            args.config,
+            root=args.root,
+            kind="file",
+            suffixes={".json"},
+        )
+        report = validate_config(load_json(path))
+        report.update(
+            {
+                "commands_executed": False,
+                "dynamic_imports_used": False,
+                "network_used": False,
+                "source": path.name,
+                "tool": TOOL,
+            }
+        )
+        emit_json(report)
+        return 0 if report["ok"] else 2
+    except (OSError, ToolError, UnicodeError) as exc:
+        return fail_json(TOOL, exc)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: frontend-design
+description: "Create distinctive, production-grade frontend interfaces with strong aesthetic intent, avoiding generic AI UI templates."
+---
+
+# Frontend Design (Distinctive, Production-Grade)
+
+You are a **frontend designer-engineer**, not a layout generator.
+
+Your goal is to create **memorable, high-craft interfaces** that:
+* Avoid generic "AI UI" patterns (cookie-cutter SaaS templates, purple gradients, default cards).
+* Express a clear aesthetic point of view with intentional design systems.
+* Are fully functional, accessible, and production-ready.
+* Translate design intent directly into clean, modern code.
+
+---
+
+## 1. Core Design Mandate
+
+Every output must satisfy **all four**:
+
+1. **Intentional Aesthetic Direction**
+   A named, explicit design stance (e.g. *editorial brutalism*, *luxury minimal*, *retro-futurist*, *industrial utilitarian*, *organic/natural*, *playful kinetic*).
+2. **Technical Correctness**
+   Real, working HTML/CSS/JS or framework code (React, Vue, Svelte, Tailwind, Vanilla CSS) — not mockups.
+3. **Visual Memorability**
+   At least one element the user will remember 24 hours later (the *Differentiation Anchor*).
+4. **Cohesive Restraint**
+   No random decoration. Every flourish must serve the aesthetic thesis.
+
+❌ No default layouts or cookie-cutter templates
+❌ No design-by-components without a system
+❌ No generic "safe" palettes (Inter/Roboto, purple-on-white)
+✅ Strong opinions, well executed with precision
+
+---
+
+## 2. Design Feasibility & Impact Index (DFII)
+
+Before building, evaluate the design direction:
+
+| Dimension | Question |
+| :--- | :--- |
+| **Aesthetic Impact (1-5)** | How visually distinctive and memorable is this direction? |
+| **Context Fit (1-5)** | Does this aesthetic suit the product, audience, and purpose? |
+| **Implementation Feasibility (1-5)** | Can this be built cleanly with available tech? |
+| **Performance Safety (1-5)** | Will it remain fast and accessible? |
+| **Consistency Risk (1-5)** | Can this be maintained across screens/components? |
+
+**Formula**: `DFII = (Impact + Fit + Feasibility + Performance) - Consistency Risk` (Target: ≥ 8)
+
+---
+
+## 3. Aesthetic Execution Rules
+
+### Typography
+* Avoid system defaults and generic fonts (Inter, Roboto, Arial).
+* Choose:
+  * 1 expressive display font (e.g., *Outfit, Syne, Space Grotesk, Playfair Display, Cinzel, Clash Display*).
+  * 1 restrained, high-legibility body font (e.g., *Plus Jakarta Sans, Geist, Satoshi, General Sans*).
+* Use typography structurally (scale, rhythm, contrast, line height).
+
+### Color & Theme
+* Commit to a **dominant color story** using CSS variables.
+* Structure: One dominant background tone, one high-contrast accent, and a refined neutral system.
+* Avoid evenly-balanced palettes where every color competes for attention.
+
+### Spatial Composition & Layout
+* Break the grid intentionally when appropriate: asymmetric placements, overlapping planes, deep negative space, or controlled typographic density.
+* White space is an active design element, not empty absence.
+
+### Motion & Micro-interactions
+* Motion must be purposeful, sparse, and high-impact (e.g., smooth entrance sequence, tactile button clicks, magnetic hover states).
+* Avoid excessive micro-motion spam that distracts from user actions.
+
+### Texture & Depth
+* Use subtle grain/noise overlays, gradient meshes, glassmorphic translucency, custom border treatments, or layered cards with purpose.
+
+---
+
+## 4. Anti-Patterns (Immediate Failure)
+
+❌ Inter / Roboto / Arial default fonts without styling
+❌ Generic purple-on-white SaaS gradient backgrounds
+❌ Default unstyled Tailwind/Bootstrap card grids
+❌ Symmetrical, predictable cookie-cutter sections
+❌ Decorative clutter with no functional or brand purpose
+
+---
+
+## 5. Output Checklist
+
+When presenting or building UI:
+- [ ] Explicit aesthetic direction named
+- [ ] DFII score ≥ 8
+- [ ] 1 distinctive differentiation anchor
+- [ ] Polished typography & color variables
+- [ ] Accessible (WCAG contrast, keyboard navigation, semantic HTML)
+- [ ] Production-ready code matches the design ambition

package/skills/generate-image/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: generate-image
+description: Generate or edit images with AI models through the OpenRouter Image API (Gemini, Seedream, Recraft, GPT-Image, Riverflow). Use for photos, illustrations, artwork, concept art, visual assets, logos, and image editing or compositing from reference images. For flowcharts, circuits, pathways, and other technical diagrams, use the scientific-schematics skill instead.
+license: MIT
+compatibility: Requires Python 3.9+ and network access to openrouter.ai. The bundled script uses only the standard library. Image generation requires the OPENROUTER_API_KEY credential and bills per request; listing models, inspecting a model, and --dry-run do not. Targets the OpenRouter Image API (POST /api/v1/images) as verified on 2026-07-31.
+allowed-tools: Read Write Edit Bash
+metadata:
+  version: "3.0"
+  skill-author: K-Dense Inc.
+  last-reviewed: "2026-07-31"
+  openclaw:
+    primaryEnv: OPENROUTER_API_KEY
+    envVars:
+      - name: OPENROUTER_API_KEY
+        required: true
+        description: OpenRouter API key used for image generation.
+---
+
+# Generate Image
+
+Generate and edit images through OpenRouter's Image API, which reaches Gemini, Seedream, Recraft,
+GPT-Image, Riverflow, and roughly thirty other models behind one request shape.
+
+## When to use
+
+**Use this skill for:** photos and photorealistic images, illustrations and artwork, concept art,
+presentation and poster visuals, logos and vector marks, image editing, and compositing from
+reference images.
+
+**Use `scientific-schematics` instead for:** flowcharts, circuit diagrams, biological pathways,
+system architecture diagrams, CONSORT diagrams, and other technical schematics.
+
+## API key
+
+Generation requires an OpenRouter key. The script resolves it in this order:
+
+1. `--api-key`
+2. the `OPENROUTER_API_KEY` environment variable
+3. `OPENROUTER_API_KEY=` in a `.env` file, searching the working directory upward, then the
+   script's own directory
+
+If none is present the script exits with setup instructions. Keys: https://openrouter.ai/keys
+
+`--list-models`, `--model-info`, and `--dry-run` need no key.
+
+## Quick start
+
+```bash
+# Generate
+python scripts/generate_image.py "A beautiful sunset over mountains"
+
+# Edit an existing image
+python scripts/generate_image.py "Make the sky purple" -i photo.jpg -o edited.png
+```
+
+Paths are relative to this skill's directory. Output defaults to `generated_image.<ext>`, where the
+extension follows the media type the model returned. The per-request cost is printed after the run.
+
+**Then look at the image.** Read the file back and check it before using it anywhere: composition,
+aspect ratio, and any text are all things models get wrong silently.
+
+## Choosing a model
+
+Default: `google/gemini-3.1-flash-image`.
+
+| Need | Model |
+| --- | --- |
+| General quality, prompt adherence | `google/gemini-3.1-flash-image` |
+| Highest Gemini tier | `google/gemini-3-pro-image` |
+| Cheap iteration | `google/gemini-3.1-flash-lite-image` (1K only), `openai/gpt-image-1-mini` |
+| Photoreal control, reproducible seeds | `bytedance-seed/seedream-4.5` |
+| Several images per request | `bytedance-seed/seedream-4.5`, `openai/gpt-image-2` (up to 10) |
+| Vector / SVG output | `recraft/recraft-v4.1-vector` |
+| Transparent background | `openai/gpt-image-1` with `--background transparent` |
+| Legible text inside the image | `recraft/recraft-v4.1`, `sourceful/riverflow-v2.5-pro` — see the caveat below |
+
+`references/models.md` carries the full catalogue with per-model parameters, allowed values, and
+prices. The live listing is authoritative and free:
+
+```bash
+python scripts/generate_image.py --list-models            # every model and its allowed values
+python scripts/generate_image.py --list-models gemini     # filtered by substring
+python scripts/generate_image.py --model-info openai/gpt-image-1   # one model, plus pricing
+```
+
+## Parameter support varies by model
+
+This is the main thing to get right. Models advertise different parameter sets **and different
+allowed values**, and sending something a model does not support is rejected, not ignored.
+
+The script checks the request against the live catalogue before spending anything, so a bad
+parameter fails locally in under a second with the legal values printed:
+
+```console
+$ python scripts/generate_image.py "abstract pattern" -m openai/gpt-image-2 --background transparent
+Error: Request rejected before billing (1 problem):
+  - background=transparent is not allowed; this model accepts: auto, opaque
+```
+
+Rough guide — but let the check be the authority, since the catalogue moves:
+
+- `--resolution` — Gemini, Seedream, Riverflow, Krea, Grok. The tiers differ: `512` only on Gemini
+  3.1 Flash, `4K` on Gemini 3 Pro / Seedream / Riverflow, and **`1K` only** on
+  `gemini-3.1-flash-lite-image` and the Krea models.
+- `--output-format` — Riverflow 2.5 only (`png`, `jpeg`, `webp`; the `fast` variant takes `jpeg`
+  alone). Gemini, OpenAI, Seedream, and Recraft all choose their own container.
+- `--quality`, `--background`, `--output-compression` — the OpenAI family, plus `--background` on
+  Riverflow 2.5. **`--background transparent` is not available on `gpt-image-2` or
+  `gpt-5.4-image-2`** — use `gpt-image-1`, `gpt-image-1-mini`, `gpt-5-image`, or `gpt-5-image-mini`.
+- `--seed` — Seedream and Krea. Not Gemini, not OpenAI.
+- `--aspect-ratio` — nearly all models, but the enum differs sharply: `gpt-image-1` accepts only
+  `1:1`, `3:2`, `2:3`, `auto`, and `gpt-5-image*` does not accept it at all.
+- `--n` — capped per model: 1 for Gemini, Riverflow, MAI and Grok, 6 for Recraft, 10 for Seedream
+  and OpenAI. The Krea models reject it outright.
+
+Pass `--dry-run` to validate and print the exact request body without generating or billing.
+`--no-preflight` skips the check when you want the API itself to arbitrate.
+
+## Writing the prompt
+
+Prompt quality decides output quality more than model choice does. Name, in one sentence each:
+
+1. **Subject** — what is in frame, and how much of it. "A single pipette tip above a 96-well plate."
+2. **Medium and style** — photograph, watercolour, 3D render, flat vector, scientific illustration.
+3. **Lighting and palette** — "soft diffuse lighting, cool blue and white palette."
+4. **Composition** — "wide shot, subject left of centre, empty space on the right for a title."
+5. **What to avoid** — "no text, no labels, no watermark."
+
+Asking for empty space where a caption or title will go is the single most useful compositional
+instruction for posters and slides.
+
+Iterate cheaply: draft on `gemini-3.1-flash-lite-image`, then regenerate the wording you settled on
+with the model you actually want. To refine rather than restart, feed the last output back as a
+reference (`-i out.png`) and describe only the change.
+
+## Editing and reference images
+
+`-i/--input` is repeatable and accepts local paths, HTTP(S) URLs, or data URLs. Local files are
+base64-encoded and sent as `input_references`.
+
+```bash
+# Single-image edit
+python scripts/generate_image.py "Add sunglasses to the person" -i portrait.png
+
+# Composite several references
+python scripts/generate_image.py "Blend these two styles" -i style_a.png -i style_b.jpg -o blend.png
+
+# Reference an image already on the web
+python scripts/generate_image.py "Restyle as a watercolor" -i https://example.com/photo.jpg
+```
+
+Reference limits differ: 16 for OpenAI, 14 for Gemini and Seedream, 10 for `riverflow-v2*-pro`,
+3 for `gemini-2.5-flash-image` and Grok, 1 for Recraft, MAI, and Krea. Accepted local formats: PNG,
+JPEG, GIF, WebP. Riverflow v2 bills $0.20 per reference image on top of the output.
+
+## Worked examples
+
+The `-o` paths are destinations the script creates, not files bundled with the skill.
+
+```bash
+# Wide hero image for a poster, with space reserved for the title
+python scripts/generate_image.py \
+  "Laboratory with modern equipment, photorealistic, well-lit, wide shot, \
+   equipment on the left, empty wall on the right, no text" \
+  --aspect-ratio 21:9 --resolution 2K -o poster/hero.png
+
+# Conceptual illustration for a manuscript — illustrative, never presented as data
+python scripts/generate_image.py \
+  "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \
+   cool palette, no text" \
+  --resolution 2K -o figures/immunotherapy_concept.png
+
+# Vector logo
+python scripts/generate_image.py \
+  "Minimal geometric fox logo, two colors" \
+  -m recraft/recraft-v4.1-vector -o assets/logo.svg
+
+# Slide background with a transparent alpha channel
+python scripts/generate_image.py \
+  "Abstract molecular pattern, subtle, blue and white, no text" \
+  -m openai/gpt-image-1 --background transparent -o slides/bg.png
+
+# Four variations in one request
+python scripts/generate_image.py \
+  "Stylized neuron network illustration" \
+  -m bytedance-seed/seedream-4.5 --n 4 -o variations.png
+# -> variations_1.png ... variations_4.png
+
+# Reproducible output
+python scripts/generate_image.py "A cat astronaut" \
+  -m bytedance-seed/seedream-4.5 --seed 42
+
+# Check a request costs nothing to get wrong
+python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run
+```
+
+## Script parameters
+
+| Flag | Purpose |
+| --- | --- |
+| `prompt` | Image description, or the edit to apply (required unless `--list-models` / `--model-info`) |
+| `-m`, `--model` | Model slug (default `google/gemini-3.1-flash-image`) |
+| `-o`, `--output` | Output path; extension defaults to the returned media type |
+| `-i`, `--input` | Reference image — path, URL, or data URL. Repeatable |
+| `--n` | Images per request, model-capped |
+| `--aspect-ratio` | `1:1`, `16:9`, `9:16`, `4:3`, `3:2`, `21:9`, … — enum differs per model |
+| `--resolution` | `512`, `1K`, `2K`, `4K` — tiers differ per model |
+| `--quality` | `auto`, `low`, `medium`, `high` (OpenAI) |
+| `--output-format` | `png`, `jpeg`, `webp` (Riverflow 2.5) |
+| `--background` | `auto`, `transparent`, `opaque` |
+| `--output-compression` | 0–100, OpenAI models |
+| `--seed` | Deterministic output where supported |
+| `--api-key` | Overrides the environment and `.env` |
+| `--timeout` | Request timeout, seconds (default 300) |
+| `--retries` | Retries for rate limits and 5xx responses (default 2) |
+| `--no-preflight` | Skip the free capability check before the billed request |
+| `--dry-run` | Validate and print the request, then exit without generating |
+| `--list-models` | Print the catalogue with allowed values, optionally filtered, then exit |
+| `--model-info` | Print one model's allowed values and pricing, then exit |
+
+There is no `--size`: no model in the catalogue accepts a `size` parameter. Shape output with
+`--aspect-ratio` and `--resolution`.
+
+## API shape
+
+For direct requests without the script:
+
+```bash
+curl -s https://openrouter.ai/api/v1/images \
+  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "google/gemini-3.1-flash-image",
+    "prompt": "A red bicycle against a white wall",
+    "aspect_ratio": "16:9"
+  }'
+```
+
+Response:
+
+```json
+{
+  "created": 1748372400,
+  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
+  "usage": {
+    "prompt_tokens": 4,
+    "completion_tokens": 1120,
+    "total_tokens": 1124,
+    "cost": 0.0672,
+    "completion_tokens_details": { "image_tokens": 1120 }
+  }
+}
+```
+
+`b64_json` is raw base64, **not** a data URL. `media_type` reflects the real format, so honour it
+when naming files — vector models return `image/svg+xml`, and `gemini-3.1-flash-lite-image` returns
+JPEG rather than PNG.
+
+Streaming (`"stream": true`) emits `image_generation.partial_image`, `image_generation.completed`,
+and `error` events, terminating with `data: [DONE]`. Only the OpenAI models support it, and the
+bundled script does not use it.
+
+Billing is all-or-nothing: a generation is either completed and billed in full, or it fails and is
+not billed — so a rejected parameter costs nothing but time. Streaming preview frames are not
+charged separately. On a bring-your-own-key account `usage.cost` reads `0` and the real amount is
+in `cost_details.upstream_inference_cost`; the script reports that figure rather than claiming the
+run was free.
+
+## Cost
+
+Per-image models are predictable: Seedream $0.04, Recraft v4.1 $0.035 (vector $0.08, pro $0.21),
+Riverflow 2.5 fast $0.019 and pro $0.13–0.17, Grok $0.05–0.07.
+
+Gemini, OpenAI, and MAI bill per output token, which scales with resolution — a 4K image costs
+roughly sixteen times a 1K one. Measured: one 1K `gemini-3.1-flash-lite-image` render is 1120
+output tokens, $0.034. At the same size `gemini-3.1-flash-image` is double that and
+`gemini-3-pro-image` four times. Draft at low resolution on a cheap model; pay for size once.
+
+## Notes and caveats
+
+- **Models cannot be trusted with text.** Words inside a generated image come back misspelled,
+  garbled, or invented. Ask for "no text" and overlay real type in LaTeX, PowerPoint, or HTML — or
+  use `scientific-schematics` when labels are the point.
+- **A generated image is an illustration, never evidence.** It shows nothing that was measured.
+  Never present one as microscopy, imaging, gel, or instrument output, never let it stand in for a
+  figure that reports results, and label it as an illustration in captions. Nature and Science both
+  require disclosure of generative-AI imagery, and several journals prohibit it outside
+  clearly-marked concept art — check the target venue before submitting.
+- Generation is a paid API call. Prefer a cheap model and low resolution while iterating on wording.
+- Generation takes roughly 5–60 seconds depending on model and resolution.
+- Reference images are uploaded to OpenRouter. Do not send unpublished or sensitive data, patient
+  images, or anything under embargo.
+- Never hardcode the API key. Keep it in the environment or an ignored `.env`.
+- Prompt specifically when editing: "change the sky to sunset colours" beats "edit the sky".
+- A refusal arrives as an HTTP 400 or 403 mentioning content policy, not as a bad image. Rephrase —
+  clinical and anatomical subjects trip moderation more often than the request warrants.
+- Rate limits and 5xx responses are retried automatically; a 4xx is final, because the request
+  itself is what needs changing.
+
+## Related skills
+
+- `scientific-schematics` — technical diagrams, flowcharts, circuits, pathways
+- `scientific-slides` — presentations that embed generated visuals
+- `latex-posters` — posters that embed hero images

package/skills/generate-image/references/models.md

@@ -0,0 +1,173 @@
+# OpenRouter image model reference
+
+Snapshot of `GET https://openrouter.ai/api/v1/images/models`, verified 2026-07-31. The catalogue
+moves and this table will drift, so treat the live listing as authoritative:
+
+```bash
+python scripts/generate_image.py --list-models            # every model, with allowed values
+python scripts/generate_image.py --list-models gemini     # filtered by substring
+python scripts/generate_image.py --model-info MODEL       # one model, plus pricing
+```
+
+No API key is needed for any of those, and nothing is billed. The script validates every request
+against this same metadata before spending money, so an unsupported parameter or an out-of-enum
+value fails locally rather than as an HTTP 400 — you do not have to memorise the tables below.
+
+## Which parameters each model accepts
+
+`n` is images per request; `refs` is the maximum number of `input_references`. Prices are the
+output-image rate the API reports; token-billed models scale with output resolution, so a 4K image
+costs roughly sixteen times a 1K one.
+
+| Model | n | refs | stream | Parameters | Output price |
+| --- | --- | --- | --- | --- | --- |
+| `google/gemini-3.1-flash-image` | 1 | 14 | no | aspect_ratio, input_references, n, resolution | $0.00006/token |
+| `google/gemini-3.1-flash-image-preview` | 1 | 14 | no | aspect_ratio, input_references, n, resolution | $0.00006/token |
+| `google/gemini-3-pro-image` | 1 | 14 | no | aspect_ratio, input_references, n, resolution | $0.00012/token |
+| `google/gemini-3-pro-image-preview` | 1 | 14 | no | aspect_ratio, input_references, n, resolution | $0.00012/token |
+| `google/gemini-3.1-flash-lite-image` | 1 | 14 | no | aspect_ratio, input_references, n, resolution | $0.00003/token |
+| `google/gemini-2.5-flash-image` | 1 | 3 | no | aspect_ratio, input_references, n | $0.00003/token |
+| `bytedance-seed/seedream-4.5` | 10 | 14 | no | aspect_ratio, input_references, n, resolution, seed | $0.04/image |
+| `openai/gpt-image-2` | 10 | 16 | yes | aspect_ratio, background, input_references, n, output_compression, quality | $0.00003/token |
+| `openai/gpt-image-1` | 10 | 16 | yes | aspect_ratio, background, input_references, n, output_compression, quality | $0.00004/token |
+| `openai/gpt-image-1-mini` | 10 | 16 | yes | aspect_ratio, background, input_references, n, output_compression, quality | $0.000008/token |
+| `openai/gpt-5.4-image-2` | 10 | 16 | yes | background, input_references, n, output_compression, quality | $0.00003/token |
+| `openai/gpt-5-image` | 10 | 16 | yes | background, input_references, n, output_compression, quality | $0.00004/token |
+| `openai/gpt-5-image-mini` | 10 | 16 | yes | background, input_references, n, output_compression, quality | $0.000008/token |
+| `krea/krea-2-large` | — | 1 | no | aspect_ratio, input_references, resolution, seed | not published |
+| `krea/krea-2-medium` | — | 1 | no | aspect_ratio, input_references, resolution, seed | not published |
+| `krea/krea-2-medium-turbo` | — | 1 | no | aspect_ratio, input_references, resolution, seed | not published |
+| `microsoft/mai-image-2.5` | 1 | 1 | no | aspect_ratio, input_references, n | $0.000047/token |
+| `microsoft/mai-image-2.5-pro` | 1 | 1 | no | aspect_ratio, input_references, n | $0.000108/token |
+| `recraft/recraft-v4.1` | 6 | 1 | no | aspect_ratio, input_references, n | $0.035/image |
+| `recraft/recraft-v4.1-pro` | 6 | 1 | no | aspect_ratio, input_references, n | $0.21/image |
+| `recraft/recraft-v4.1-vector` | 6 | 1 | no | aspect_ratio, input_references, n | $0.08/image |
+| `recraft/recraft-v4.1-pro-vector` | 6 | 1 | no | aspect_ratio, input_references, n | $0.30/image |
+| `recraft/recraft-v4.1-utility` | 6 | 1 | no | aspect_ratio, input_references, n | $0.035/image |
+| `recraft/recraft-v4.1-utility-pro` | 6 | 1 | no | aspect_ratio, input_references, n | $0.21/image |
+| `recraft/recraft-v4` | 6 | 1 | no | aspect_ratio, input_references, n | $0.04/image |
+| `recraft/recraft-v4-pro` | 6 | 1 | no | aspect_ratio, input_references, n | $0.25/image |
+| `recraft/recraft-v4-vector` | 6 | 1 | no | aspect_ratio, input_references, n | $0.08/image |
+| `recraft/recraft-v4-pro-vector` | 6 | 1 | no | aspect_ratio, input_references, n | $0.30/image |
+| `recraft/recraft-v3` | 6 | 1 | no | aspect_ratio, input_references, n | $0.04/image |
+| `sourceful/riverflow-v2.5-pro` | 1 | 10 | no | aspect_ratio, background, input_references, n, output_format, resolution | $0.13/image; $0.15 at 2K; $0.17 at 4K |
+| `sourceful/riverflow-v2.5-fast` | 1 | 4 | no | aspect_ratio, background, input_references, n, output_format, resolution | $0.019/image; $0.021 at 2K |
+| `sourceful/riverflow-v2-pro` | 1 | 10 | no | aspect_ratio, input_references, n, resolution | $0.15/image; $0.33 at 4K |
+| `sourceful/riverflow-v2-fast` | 1 | 4 | no | aspect_ratio, input_references, n, resolution | $0.02/image; $0.04 at 2K |
+| `x-ai/grok-imagine-image-quality` | 1 | 3 | no | aspect_ratio, input_references, n, resolution | $0.05/image at 1K; $0.07 at 2K |
+
+Riverflow also bills reference images: v2 charges $0.20 per `input_reference` and $0.03 per input
+font. The Krea models publish no price through the API — check the cost the script reports after a
+run before using them at volume.
+
+## Which values each parameter accepts
+
+Support is not enough: the allowed **values** differ per model too, and an out-of-enum value is
+rejected the same way an unsupported parameter is. A dash means the model does not accept the
+parameter at all.
+
+| Model | resolution | output_format | background | quality | seed |
+| --- | --- | --- | --- | --- | --- |
+| `google/gemini-3.1-flash-image` | 512, 1K, 2K, 4K | — | — | — | — |
+| `google/gemini-3.1-flash-image-preview` | 512, 1K, 2K, 4K | — | — | — | — |
+| `google/gemini-3-pro-image` | 1K, 2K, 4K | — | — | — | — |
+| `google/gemini-3-pro-image-preview` | 1K, 2K, 4K | — | — | — | — |
+| `google/gemini-3.1-flash-lite-image` | **1K only** | — | — | — | — |
+| `google/gemini-2.5-flash-image` | — | — | — | — | — |
+| `bytedance-seed/seedream-4.5` | 1K, 2K, 4K | — | — | — | yes |
+| `openai/gpt-image-2` | — | — | **auto, opaque** | auto, low, medium, high | — |
+| `openai/gpt-image-1` | — | — | auto, transparent, opaque | auto, low, medium, high | — |
+| `openai/gpt-image-1-mini` | — | — | auto, transparent, opaque | auto, low, medium, high | — |
+| `openai/gpt-5.4-image-2` | — | — | **auto, opaque** | auto, low, medium, high | — |
+| `openai/gpt-5-image` | — | — | auto, transparent, opaque | auto, low, medium, high | — |
+| `openai/gpt-5-image-mini` | — | — | auto, transparent, opaque | auto, low, medium, high | — |
+| `krea/krea-2-*` | **1K only** | — | — | — | yes |
+| `microsoft/mai-image-2.5`, `-pro` | — | — | — | — | — |
+| `recraft/*` | — | — | — | — | — |
+| `sourceful/riverflow-v2.5-pro` | 1K, 2K, 4K | png, jpeg, webp | auto, transparent, opaque | — | — |
+| `sourceful/riverflow-v2.5-fast` | 1K, 2K | **jpeg only** | auto, transparent, opaque | — | — |
+| `sourceful/riverflow-v2-pro`, `-fast` | 1K, 2K, 4K | — | — | — | — |
+| `x-ai/grok-imagine-image-quality` | 1K, 2K | — | — | — | — |
+
+Traps worth knowing, because each one is a wasted round trip:
+
+- `transparent` is **not** available on `gpt-image-2` or `gpt-5.4-image-2`, the newest OpenAI
+  models. Use `gpt-image-1`, `gpt-image-1-mini`, `gpt-5-image`, `gpt-5-image-mini`, or Riverflow 2.5.
+- `512` exists only on Gemini 3.1 Flash. `flash-lite` and the Krea models take `1K` and nothing else.
+- `output_compression` is offered only by the OpenAI models, and none of them accept
+  `output_format` — the container is theirs to choose.
+- **No model accepts `size`.** Shape the output with `aspect_ratio` and `resolution`.
+- **No model accepts `output_format: svg`.** SVG comes from the Recraft vector models, which return
+  `media_type: image/svg+xml` regardless of that parameter.
+
+### Aspect ratio enums
+
+`aspect_ratio` is the most varied parameter, and three OpenAI models do not accept it at all.
+
+| Models | Allowed |
+| --- | --- |
+| `gemini-3.1-flash-image`, `-preview`, `flash-lite` | 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 |
+| `gemini-3-pro-image`, `-preview`, `gemini-2.5-flash-image` | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
+| `seedream-4.5` | 1:1, 1:2, 2:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:19.5, 19.5:9, 9:20, 20:9, 9:21, 21:9, auto |
+| `gpt-image-2` | 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, auto |
+| `gpt-image-1`, `gpt-image-1-mini` | **1:1, 3:2, 2:3, auto only — no 16:9** |
+| `gpt-5-image`, `gpt-5-image-mini`, `gpt-5.4-image-2` | **not accepted at all** |
+| `recraft/*` | 1:1, 4:3, 3:4, 16:9, 9:16, auto |
+| `riverflow-*` | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, auto |
+| `mai-image-2.5`, `-pro` | 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto |
+| `krea/krea-2-*` | 1:1, 4:3, 3:2, 16:9, 4:5, 2:3, 9:16 |
+| `grok-imagine-image-quality` | 1:1, 3:4, 4:3, 9:16, 16:9, 2:3, 3:2, 9:19.5, 19.5:9, 9:20, 20:9, 1:2, 2:1, auto |
+
+## Choosing a model
+
+- **General quality and prompt adherence** — `google/gemini-3.1-flash-image` (skill default), or
+  `google/gemini-3-pro-image` for the higher tier at double the token rate.
+- **Cheap iteration** — `google/gemini-3.1-flash-lite-image` (half the flash rate, but 1K only) or
+  `openai/gpt-image-1-mini`. Measured: one 1K `flash-lite` image is 1120 output tokens, $0.034.
+- **Photoreal and artistic control** — `bytedance-seed/seedream-4.5` (flat $0.04/image, seeded) or
+  `microsoft/mai-image-2.5-pro`.
+- **Reproducible output from a seed** — `bytedance-seed/seedream-4.5` and the Krea models. The
+  Gemini and OpenAI families do not accept `seed`.
+- **Batches** — `bytedance-seed/seedream-4.5` or the OpenAI family, up to 10 per request. Gemini,
+  Riverflow, MAI, and Grok cap at 1; Recraft at 6.
+- **True vector output (SVG)** — `recraft/recraft-v4.1-vector`, `recraft/recraft-v4-vector`, and the
+  `-pro-vector` variants. These return `media_type: image/svg+xml`.
+- **Text rendered legibly inside the image** — Recraft (which takes `text_layout` as a passthrough
+  parameter) and Riverflow are the strongest, but no model is dependable. Prefer overlaying text in
+  LaTeX, PowerPoint, or HTML.
+- **Transparent backgrounds** — `gpt-image-1`, `gpt-image-1-mini`, `gpt-5-image`,
+  `gpt-5-image-mini`, or `riverflow-v2.5-*`.
+- **Heavy multi-reference compositing** — OpenAI (16 references), Gemini and Seedream (14),
+  `riverflow-v2*-pro` (10). Recraft, MAI, and Krea accept exactly 1.
+
+## Passthrough parameters
+
+`GET /api/v1/images/models/<model>/endpoints` lists `allowed_passthrough_parameters` — provider
+options the Image API forwards but the bundled script does not expose. Notable sets:
+
+- Recraft: `style`, `controls`, `text_layout`
+- Krea: `styles`, `moodboards`, `image_style_references`, `creativity`, `intensity`, `complexity`,
+  `movement`, `strength`
+- OpenAI: `moderation`
+- Gemini: `cachedContent`
+- Riverflow: `font_inputs`
+
+Send a direct request when you need one of these. `--model-info MODEL` prints the list.
+
+## Provider routing
+
+The Image API accepts the same `provider` block as chat completions — `provider.only`,
+`provider.order`, `provider.ignore`, `provider.sort` (`price`, `throughput`, `latency`), and
+`provider.allow_fallbacks`. The bundled script does not expose these; send a direct request when
+routing control matters.
+
+## Billing
+
+Image billing is all-or-nothing: a generation either completes and is billed in full, or fails and
+is not billed. A rejected parameter therefore costs nothing but time. Partial preview frames
+delivered during streaming are not charged separately.
+
+Per-request cost comes back in `usage.cost`, which the script prints. On a bring-your-own-key
+account `usage.cost` is `0` and the real figure is in `cost_details.upstream_inference_cost`, where
+the upstream provider bills you directly — the script reports that instead of claiming the
+generation was free.