generate-ai-image

name	generate-ai-image
description	Use when generating AI cover images or illustrations via OpenRouter API (AI image, OpenRouter, cover image, WeChat, text-to-image, Gemini, image generation).
argument-hint	Description of the image to generate, e.g.: WeChat cover for agent-based workflow article, illustration showing 12-stage delivery lifecycle
user-invocable	true

Generate AI Image (Nano Banana 2)

Generate article cover images and illustrations by calling the OpenRouter API. The calling agent is responsible for crafting the complete, detailed image generation prompt. The script takes this prompt and sends it directly to the image generation model — no additional LLM prompt optimization is performed by default.

If explicitly requested (via -OptimizePrompt / --optimize-prompt), the script can optionally call an LLM to refine the description into an optimized prompt before image generation.

The default image model is Nano Banana 2 (google/gemini-3.1-flash-image-preview), Google's state-of-the-art image generation model that uses the chat/completions endpoint with modalities: ["image", "text"]. Fallback models using the images/generations endpoint (e.g., openai/dall-e-3) are also supported.

When to Use

• The task needs a polished cover image or illustration for a WeChat article, blog post, or documentation page.
• A text description or article topic needs to be converted into a visually appealing image.
• The image needs custom composition, color, and style beyond what Mermaid diagrams can produce.

When Not to Use

• The diagram is a technical flowchart, sequence diagram, or architecture diagram — use generate-mermaid-flowchart instead.
• The image is a simple screenshot or code block.
• No API credentials are configured.

Prerequisites

• A .env file at the repository root with:
  • openrouter_url — OpenRouter API base URL (e.g., https://openrouter.ai/api/v1)
  • openrouter_key — OpenRouter API key
• Network access to OpenRouter API.
• For image generation: the default model is google/gemini-3.1-flash-image-preview (Nano Banana 2). Alternative models like openai/dall-e-3 can be specified via the ImageModel parameter.
• For optional prompt optimization: an OpenRouter-supported text LLM (default: openai/gpt-4o-mini). Only used when -OptimizePrompt / --optimize-prompt is specified.

Procedure

1. Craft the image prompt. The calling agent must compose a complete, detailed image generation prompt including:

   • Subject and composition: What the image should depict, layout, and key visual elements.
   • Style: Visual style (e.g., flat design, isometric, minimalist, cartoon).
   • Color and mood: Color palette, tone, and atmosphere.
   • Format constraints: Mention landscape or square as appropriate.
   • Negative guidance: What to avoid (e.g., no text, no photorealistic).

   Use the tips in the "Tips for Better Results" section below to write an effective prompt.

2. Run the generation script.

   • Windows: .github/skills/generate-ai-image/scripts/generate-image.ps1 -Description "<complete prompt>" -Style cover -OutputFile <path.png>
   • Linux/macOS: .github/skills/generate-ai-image/scripts/generate-image.sh "<complete prompt>" <path.png> cover
   • With optional LLM optimization: Add -OptimizePrompt (PowerShell) or --optimize-prompt (Bash) when the user explicitly requests prompt refinement or provides only a brief topic instead of a detailed prompt.

   The script will:

   1. Read API credentials from .env.
   2. Use the provided description directly as the image prompt (or, if optimization is requested, call the text LLM first to refine it).
   3. Save the prompt to a .prompt.txt file alongside the output image.
   4. Call the image generation model with the prompt.
   5. Save the resulting image to the output path.

3. Verify the output. Confirm both the output image file and the .prompt.txt prompt file exist and are non-empty. The prompt file records the exact prompt used for reproducibility and iterative refinement.

4. Update references. Insert the image into the target document:

   ![Description](relative/path/to/image.png)
   

Script Reference

Script	Platform	Purpose
scripts/generate-image.ps1	Windows (PowerShell)	Generate AI image via OpenRouter API
scripts/generate-image.sh	Linux / macOS (Bash)	Generate AI image via OpenRouter API

Parameters

Parameter	Required	Default	Description
Description	Yes	—	Complete image generation prompt crafted by the calling agent
OutputFile	No	ai-image-<timestamp>.png	Output image file path
Style	No	illustration	Image style: cover (1792×1024) or illustration (1024×1024)
OptimizePrompt	No	off	When set, calls an LLM to optimize the description into a refined prompt before generation. Use only when the user explicitly requests it or provides only a brief topic
PromptModel	No	openai/gpt-4o-mini	LLM model for prompt optimization (only used with OptimizePrompt)
ImageModel	No	google/gemini-3.1-flash-image-preview	Image generation model
EnvFile	No	.env	Path to .env file with API credentials

Output Guidance

• WeChat cover images: Use --style cover for 1792×1024 landscape format. WeChat requires minimum 900×383.
• Article illustrations: Use --style illustration for 1024×1024 square format.
• Place WeChat article images under assets/wechat/.
• Place general documentation images under assets/images/.
• Use descriptive filenames: workflow-cover.png, lifecycle-illustration.png.
• The optimized prompt is automatically saved as a .prompt.txt file next to the image (e.g., workflow-cover.prompt.txt). Commit this file alongside the image for reproducibility.

Prompt Authoring Responsibility

The calling agent (not the script) is responsible for writing the complete image generation prompt. This avoids an extra LLM round-trip and produces more predictable results because the agent has full context about the article, design goals, and visual requirements.

The -OptimizePrompt / --optimize-prompt flag is available as a fallback when:

• The user explicitly asks for prompt optimization.
• The user provides only a brief topic (e.g., "agent workflow") rather than a detailed visual description.

Supported Image Models (via OpenRouter)

The default model is google/gemini-3.1-flash-image-preview (Nano Banana 2), which uses the chat/completions endpoint with modalities: ["image", "text"]. Alternative models that use the legacy images/generations endpoint (such as openai/dall-e-3) are also supported — the script auto-detects which API to use based on the model name.

• google/gemini-3.1-flash-image-preview — default, Nano Banana 2, fast and cost-effective ($0.50/M input, $3/M output tokens)
• openai/dall-e-3 — high quality, supports 1024×1024 / 1024×1792 / 1792×1024 (uses images/generations endpoint)
• openai/gpt-image-1 — GPT Image model (uses images/generations endpoint)
• Other models available through your OpenRouter subscription

Tips for Better Results

1. Be specific. "A modern flat-design illustration of a 12-stage software delivery lifecycle with color-coded phases" produces better results than "software workflow".
2. Specify style. Include terms like "flat design", "isometric", "minimalist", "tech illustration" in the description.
3. Avoid text. AI-generated text in images is usually garbled. Describe visual elements instead.
4. Iterate. Run multiple times with refined descriptions and pick the best result.
5. Use the two-step flow. The script first generates an optimized prompt — review it in the output to understand what was sent to the image model.