BlockRun MCP

Official

Overview Schema Source Related Servers Discussions Admin

blockrun_image

Generate or edit AI images from text prompts or source images, paying per image with USDC on Base or Solana and needing no API keys.

Instructions

Generate or edit images via BlockRun. Pays with USDC on the ACTIVE chain — Base or Solana (see blockrun_wallet) — no separate API keys needed.

Actions:

generate (default): Create image from text prompt
edit: Transform an existing image using img2img

Generation models (1024x1024 base price; larger sizes cost more on gpt-image-*):

openai/gpt-image-2 ($0.06–0.12) — flagship, reasoning-driven, multilingual on-image text + character consistency (default)
openai/gpt-image-1 ($0.02–0.04) — GPT native image generation
google/nano-banana ($0.05) — Gemini-family image model
google/nano-banana-2 ($0.09) — Gemini 3.1 Flash, pro-level quality at Flash speed (1024x1024 only)
google/nano-banana-pro ($0.10; $0.15 at 4096px) — up to 4K, strongest photorealism
xai/grok-imagine-image ($0.02) — stylized, fast
xai/grok-imagine-image-pro ($0.07) — higher quality Grok Imagine
zai/cogview-4 ($0.015) — cheapest, photorealistic detailed scenes
bytedance/seedream-5-pro ($0.045; $0.09 when both dimensions exceed 1024) — Seedream 5.0 Pro; cheap widescreen at 1280x720 / 2048x1024, large formats up to 2848x1600

Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/nano-banana, google/nano-banana-2, google/nano-banana-pro Multi-image edit: pass an array of 2–4 source images to "image" to fuse them in one render (openai/* up to 4, google/* up to 3) — e.g. a subject plus a sprite layout guide, or a reference plus a brand logo. Source images and masks accept a base64 data URI, an http(s) URL, or a local file path (auto-encoded). Inpaint mask (openai/gpt-image-* only) via "mask"; not combinable with multiple source images.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mask`	No	Inpaint mask for edit action (openai/gpt-image-* only): a base64 data URI, http(s) URL, or local file path. Transparent areas of the mask are regenerated. Cannot be combined with multiple source images.
`size`	No	Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro), 1280x720 / 2048x1024 / 2048x2048 / 2848x1600 (seedream-5-pro)	1024x1024
`image`	No	Source image(s) for edit action: a base64 data URI, an http(s) URL, or a local file path (auto-encoded to a data URI) — or an array of 2–4 to fuse into one render (e.g. subject + layout guide, or reference + brand logo). openai/* accepts up to 4, google/* up to 3; a mask cannot be combined with multiple images.
`model`	No	Model to use (default: openai/gpt-image-2 for both generate and edit). gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts.
`action`	No	generate: create from text; edit: transform existing image	generate
`inline`	No	Return a small inline image preview (thumbnail) the client can render in-conversation, in addition to the full-resolution URL. Defaults to the BLOCKRUN_INLINE_IMAGES env setting (off unless set). Rich clients (e.g. the VS Code extension) render it; plain terminals ignore it. Off keeps responses lightweight.
`prompt`	Yes	Image description or edit instructions
`agent_id`	No	Agent identifier for budget tracking and enforcement.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.51.1Sep 16, 2026

removedInput schema / properties / quality

Removed value: -{
-  "default": "standard",
-  "enum": [
-    "standard",
-    "hd"
-  ],
-  "type": "string"
-}

Changed1 schema field changedv0.45.1Sep 2, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```

Changed2 schema fields changedv0.37.1Aug 7, 2026

changedInput schema / properties / model / enum

Previous value: -[
-  "zai/cogview-4",
-  "google/nano-banana",
-  "google/nano-banana-pro",
-  "openai/gpt-image-1",
-  "openai/gpt-image-2",
-  "xai/grok-imagine-image",
-  "xai/grok-imagine-image-pro"
-]New value: +[
+  "zai/cogview-4",
+  "google/nano-banana",
+  "google/nano-banana-2",
+  "google/nano-banana-pro",
+  "openai/gpt-image-1",
+  "openai/gpt-image-2",
+  "xai/grok-imagine-image",
+  "xai/grok-imagine-image-pro",
+  "bytedance/seedream-5-pro"
+]

changedInput schema / properties / size / description

Previous value: -"Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro)"New value: +"Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro), 1280x720 / 2048x1024 / 2048x2048 / 2848x1600 (seedream-5-pro)"

Changed5 schema fields changedv0.25.2Jun 29, 2026

addedInput schema / properties / image / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "maxItems": 4,
+    "minItems": 1,
+    "type": "array"
+  }
+]

changedInput schema / properties / image / description

Previous value: -"Source image for edit action: base64-encoded image or URL"New value: +"Source image(s) for edit action: a base64 data URI, an http(s) URL, or a local file path (auto-encoded to a data URI) — or an array of 2–4 to fuse into one render (e.g. subject + layout guide, or reference + brand logo). openai/* accepts up to 4, google/* up to 3; a mask cannot be combined with multiple images."

removedInput schema / properties / image / type
```
Removed value: -"string"
```

addedInput schema / properties / inline

Added value: +{
+  "description": "Return a small inline image preview (thumbnail) the client can render in-conversation, in addition to the full-resolution URL. Defaults to the BLOCKRUN_INLINE_IMAGES env setting (off unless set). Rich clients (e.g. the VS Code extension) render it; plain terminals ignore it. Off keeps responses lightweight.",
+  "type": "boolean"
+}

addedInput schema / properties / mask

Added value: +{
+  "description": "Inpaint mask for edit action (openai/gpt-image-* only): a base64 data URI, http(s) URL, or local file path. Transparent areas of the mask are regenerated. Cannot be combined with multiple source images.",
+  "type": "string"
+}

Changed4 schema fields changedv0.22.0Jun 18, 2026

changedInput schema / properties / model / description

Previous value: -"Model to use (default: dall-e-3 for generate, gpt-image-2 for edit). xai/grok-imagine-image is stylized and fast; xai/grok-imagine-image-pro is higher quality; gpt-image-2 is the newest edit-capable model with stronger instruction following."New value: +"Model to use (default: openai/gpt-image-2 for both generate and edit). gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts."

changedInput schema / properties / model / enum

Previous value: -[
-  "zai/cogview-4",
-  "openai/dall-e-3",
-  "together/flux-schnell",
-  "google/nano-banana",
-  "openai/gpt-image-1",
-  "openai/gpt-image-2",
-  "xai/grok-imagine-image",
-  "xai/grok-imagine-image-pro"
-]New value: +[
+  "zai/cogview-4",
+  "google/nano-banana",
+  "google/nano-banana-pro",
+  "openai/gpt-image-1",
+  "openai/gpt-image-2",
+  "xai/grok-imagine-image",
+  "xai/grok-imagine-image-pro"
+]

addedInput schema / properties / size / description

Added value: +"Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro)"

removedInput schema / properties / size / enum

Removed value: -[
-  "1024x1024",
-  "1792x1024",
-  "1024x1792"
-]

First observedv0.16.2May 29, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses payment mechanics (USDC on active chain), per-model pricing, multi-image and mask constraints, source input formats, and the inline preview behavior (full-resolution URL plus optional thumbnail). This gives the agent a rich behavioral model of what happens when the tool is invoked.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but earns every word. It is structured with clear sections: purpose/payment, actions, model list with pricing and capabilities, edit specifics, multi-image rules, source formats, and mask constraints. Critical info (purpose, payment) is front-loaded, and the bulletized model list aids scannability despite the density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, no output schema, and multiple model-specific behaviors, the description covers all necessary invocation details: required prompt, defaults, pricing, chain/payment, image sources, action variations, inline output preview, and constraints. An agent can make a confident, correct call using only the description and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial semantics: it maps each model to its specific use case and cost, explains default model behavior per action, clarifies multi-image array limits per provider, and details mask compatibility rules. This goes far beyond the schema's short field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Generate or edit images via BlockRun', a specific verb and resource, and clearly distinguishes itself from media siblings like blockrun_video or blockrun_music. The generate/edit action split further clarifies the two main operational modes, leaving no ambiguity about the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance for selecting actions (generate vs edit) and models, including cost/quality trade-offs and defaults ('gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts'). It also directs the agent to blockrun_wallet for payment context retain full clarity. While it does not name other sibling tools as exclusions, the tool name and media-type focus make when to use it unmistakable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blockrun_image

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools