--- name: k-dense-ai/generate-image source: https://app.decimal.ai/s/k-dense-ai-generate-image@1/SKILL.md source_sha256: 2068602c2154 --- # 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.`, 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": "", "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