imagegen

# Image Generation & Editing Generate or edit images through ClawRouter. Payment is automatic via x402. **Shortcuts:** - Slash: `/cr-imagegen <prompt> [--model=<alias>] [--size=1024x1024] [--n=1]` (`/imagegen` still accepted in chat for backward compatibility) - Partner tool: `blockrun_image_generation` (LLM-callable) / `blockrun_image_edit` (inpainting) --- ## Generate an Image POST to `http://localhost:8402/v1/images/generations`: ```json { "model": "google/nano-banana", "prompt": "a golden retriever surfing on a wave", "size": "1024x1024", "n": 1 } ``` Response: ```json { "created": 1741460000, "data": [{ "url": "http://localhost:8402/images/abc123.png" }] } ``` Display inline: `` ### Model Selection | Alias | Full ID | Sizes | Best for | | ------------------ | ------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `nano-banana` | `google/nano-banana` | 1024×1024 | Default — fast, cheap, good quality | | `banana-2` | `google/nano-banana-2` | 1024×1024 | Gemini 3.1 Flash imagegen — sharper than nano-banana at 1K | | `banana-pro` | `google/nano-banana-pro` | 1024×1024, 2048×2048, 4096×4096 | High-res, large format | | `gpt-image` | `openai/gpt-image-1` | 1024×1024, 1536×1024, 1024×1536 | Budget option; supports editing | | `gpt-image-2` | `openai/gpt-image-2` | 1024×1024, 1536×1024, 1024×1536 | Photorealistic, reasoning-driven, text rendering (slow — proxy polls up to 5min); legacy `dalle` alias routes here | | `flare` | `openai/gpt-image-2.5-flare` | 1024×1024, 1536×1024, 1024×1536 | GPT Image 2.5, fast — top OpenAI quality, caller can pick `quality` at a flat price | | `sunburst` | `openai/gpt-image-2.5-sunburst` | 1024×1024, 1536×1024, 1024×1536 | GPT Image 2.5, precision — best for high-fidelity edits | | `seedream` | `bytedance/seedream-5-pro` | up to 2848×1600 / 2304×1728 | Flagship quality, reference-image support | | `grok-imagine` | `xai/grok-imagine-image` | 1024×1024 | xAI Grok image style | | `grok-imagine-2` | `xai/grok-imagine-image-2.0` | 1024×1024 | Grok Imagine 2.0 — between grok-imagine and pro | | `grok-imagine-pro` | `xai/grok-imagine-image-pro` | 1024×1024 | Grok high-quality | | `cogview` | `zai/cogview-4` | 512×512 to 1440×1440 | Cheapest — Zhipu CogView | **Prices:** per image, and they change — look the model up live instead of trusting a number here. `GET https://blockrun.ai/api/v1/models` (Solana: `https://sol.blockrun.ai/api/v1/models`), find the entry whose `id` is the Full ID above, and read `pricing.per_image` plus `pricing.transaction_fee`. Larger sizes or higher `quality` can cost more than the listed base rate; the exact amount is quoted in the HTTP 402 challenge before anything is signed. **Choosing a model:** - Default → `nano-banana` - "high res" / "large" → `banana-pro` - "photorealistic" / complex scenes → `gpt-image-2` - "flagship quality" / reference image → `seedream` - "budget" / "cheap" → `cogview` - "top quality" / "best OpenAI" → `flare` (fast) or `sunburst` (precision) - "editable" / "inpainting" → `gpt-image` (cheapest), `gpt-image-2`, or `sunburst` (most precise) - "artistic" / flexible content → `grok-imagine` - "grok style" → `grok-imagine` or `grok-imagine-pro` **Choosing a size:** - Default: `1024x1024` (the only size every model accepts) - Portrait: `1024x1536` (gpt-image / gpt-image-2 / flare / sunburst) or `1728x2304` (seedream) - Landscape: `1536x1024` (gpt-image / gpt-image-2 / flare / sunburst), `1344x768` (cogview), or `2048x1024` / `1280x720` (seedream) - High-res: `2048x2048` / `4096x4096` with `banana-pro`; `2848x1600` with `seedream` - The gateway validates size per model BEFORE payment and rejects unknown ones — do not invent sizes outside each model's list above --- ## Edit an Existing Image POST to `http://localhost:8402/v1/images/image2image`: ```json { "model": "openai/gpt-image-1", "prompt": "make the background a snowy mountain landscape", "image": "https://example.com/photo.jpg", "size": "1024x1024", "n": 1 } ``` ClawRouter automatically downloads URLs and reads local file paths — pass them directly, no manual base64 conversion needed. Optional `mask` field: a second image (URL or path) that marks which areas to edit (white = edit, black = keep). Response is identical to generation: ```json { "created": 1741460000, "data": [{ "url": "http://localhost:8402/images/xyz456.png", "revised_prompt": "..." }] } ``` **Supported models for editing:** `openai/gpt-image-1` (default), `openai/gpt-image-2`, `openai/gpt-image-2.5-sunburst`, `google/nano-banana`, `google/nano-banana-2`, `google/nano-banana-pro`. `mask` works with the OpenAI models only. `openai/gpt-image-2.5-flare` cannot edit. --- ## Example Interactions **User:** Draw me a cyberpunk city at night → POST to `/v1/images/generations`, model `nano-banana`, prompt as given. **User:** Generate a high-res portrait of a samurai → POST to `/v1/images/generations`, model `seedream`, size `1728x2304`. **User:** Edit this photo to add a sunset background: https://example.com/portrait.jpg → POST to `/v1/images/image2image`, model `gpt-image`, image = the URL, prompt = "add a warm sunset background". **User:** Change the background in my image to a beach (attaches local file) → POST to `/v1/images/image2image`, image = the local file path, prompt describes the change. --- ## Notes - Payment is automatic, and which rail it uses depends on how ClawRouter was started: an x402 USDC micropayment from the user's wallet, or a draw on account credit if a BlockRun API key is configured. Either way the agent does nothing. - If the call fails with a payment error, check `GET http://localhost:8402/health` and read `authMode` before telling the user how to fix it: `wallet` → fund the wallet at [blockrun.ai](https://blockrun.ai); `api-key` → top up account credit at [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits). Naming the wrong one sends the user to a page that cannot fix their error. - Google models may return base64 internally — ClawRouter uploads automatically and returns a hosted URL - OpenAI image models enforce OpenAI content policy; use `nano-banana` or `grok-imagine` for more flexibility - Image editing works with gpt-image-1/2, sunburst and the nano-banana models (not flare, seedream, grok or cogview); generation supports all listed models