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