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:

{
  "model": "google/nano-banana",
  "prompt": "a golden retriever surfing on a wave",
  "size": "1024x1024",
  "n": 1
}

Response:

{
  "created": 1741460000,
  "data": [{ "url": "http://localhost:8402/images/abc123.png" }]
}

Display inline: ![generated image](http://localhost:8402/images/abc123.png)

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:

{
  "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:

{
  "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; api-key → top up account credit at 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

imagegen