Image Editing API (img2img)

Edit existing images — pass one or more source images and describe what to change.

Endpoint

POST https://blockrun.ai/api/v1/images/image2image       # Base
POST https://sol.blockrun.ai/api/v1/images/image2image    # Solana
GET  https://blockrun.ai/api/v1/images/generations/{id}  # poll (async slow path only — edits share the generation job store)

Request

{
  "model": "openai/gpt-image-1",
  "prompt": "change the background to a starry sky",
  "image": "data:image/png;base64,<base64-data>",
  "mask": "data:image/png;base64,<base64-data>",
  "size": "1024x1024",
  "n": 1
}

Parameters

Unknown fields are ignored. A body that is not valid JSON (or an unparsable multipart form) returns 400; a body that fails validation returns 400 { "error": "Invalid request body", "details": [...] }.

Accepted image formats

Every image and mask value is decoded and sniffed before the 402, so bad input is a 400 and never costs a signed round-trip. To pass the gate a data URI must:

• start with data:image/, and
• decode to real image bytes — PNG, JPEG, GIF, BMP, WEBP, or an ISO-BMFF container (HEIC / HEIF / AVIF). A syntactically valid URI with garbage bytes (e.g. data:image/png;base64,AAAA) is rejected with image data URI does not decode to a recognizable image (expected PNG, JPEG, GIF, BMP, WEBP, or HEIC/HEIF/AVIF).

The gate only rejects undecodable data; the model is the final authority on formats. Google Nano Banana models accept HEIC/HEIF (the iPhone camera default), while OpenAI GPT Image models do not — sending one there returns 400 { "error": "Invalid input image", "details": "..." } from the model's own check, still without a charge. There is no separate byte cap on the source images beyond what fits in one HTTP request.

Supported Models

Prices are what the 402 challenge quotes and what is billed for one edit at that size — catalog rate + 5% + the flat $0.001 transaction fee (see Pricing).

Hybrid sync/async flow & settlement

Like /v1/images/generations, this endpoint is hybrid — it is not always synchronous:

• Fast edits (≤30s inline window): 200 with the standard { id, created, data: [...] } body below. Payment settles inside this response.
• Slow edits (>30s — openai/gpt-image-2 single-image edits routinely take 45–90s, and multi-image fusion longer; its upstream call is allowed up to 600s): 202 with an async job envelope { id, object: "image.edit.job", status, poll_url, price, payment_status: "verified" }. Nothing has been charged yet. Poll GET {poll_url} (it lives under /v1/images/generations/{id} — edits share the same job store) with an x-payment header from the same wallet every 2–5s. USDC settles exactly once, on the first poll that observes status: "completed". A job that ends failed, or that you never poll, is never charged.

The envelope fields, poll responses, status enum (queued → in_progress → completed | failed), replay recovery (402 PAYMENT_REPLAY with job_id + poll_url) and settlement guarantees are identical to image generation — see the full spec there. Go SDK blockrun-llm-go ≥ v0.17.0 (ImageClient.Edit) handles the hybrid flow transparently and always returns the synchronous shape.

Response

{
  "id": "img_8f3a…",
  "created": 1706000000,
  "data": [
    {
      "url": "data:image/png;base64,…",
      "revised_prompt": "A photo with the background changed to..."
    }
  ],
  "price": { "amount": "0.064000", "currency": "USD" },
  "payment": { "status": "settled", "tx_hash": "0x…", "network": "base" }
}

Headers: PAYMENT-RESPONSE (x402 settlement receipt) and X-Payment-Receipt (the on-chain tx hash).

Response Fields

Examples

Via ClawRouter (recommended)

The easiest way is using ClawRouter's /img2img slash command, which reads local files automatically:

/img2img --image ~/photo.png change the background to a starry sky
/img2img --image ./cat.jpg --mask ./mask.png remove the background
/img2img --image /tmp/portrait.png --size 1536x1024 add a hat

Via ClawRouter API

ClawRouter handles x402 payments automatically:

# First, convert your image to base64
IMAGE_B64=$(base64 -i ~/photo.png)

curl -X POST http://localhost:8402/v1/images/image2image \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"openai/gpt-image-1\",
    \"prompt\": \"change the background to a starry sky\",
    \"image\": \"data:image/png;base64,${IMAGE_B64}\",
    \"size\": \"1024x1024\"
  }"

Direct API (cURL)

IMAGE_B64=$(base64 -i ~/photo.png)

# Base
curl -X POST https://blockrun.ai/api/v1/images/image2image \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT_HEADER" \
  -d "{
    \"model\": \"openai/gpt-image-1\",
    \"prompt\": \"change the background to a starry sky\",
    \"image\": \"data:image/png;base64,${IMAGE_B64}\",
    \"size\": \"1024x1024\"
  }"

# Solana
curl -X POST https://sol.blockrun.ai/api/v1/images/image2image \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT_HEADER" \
  -d "{
    \"model\": \"openai/gpt-image-1\",
    \"prompt\": \"change the background to a starry sky\",
    \"image\": \"data:image/png;base64,${IMAGE_B64}\",
    \"size\": \"1024x1024\"
  }"

Mask Usage

The mask is passed to the model unchanged, so it follows the OpenAI Images edit convention: a PNG with an alpha channel, the same dimensions as the source image.

• Fully transparent pixels (alpha 0) = areas to edit (the model generates new content here)
• Opaque pixels = areas to keep unchanged

If no mask is provided, the model edits the entire image based on the prompt. The mask goes through the same pre-402 byte check as image.

Multi-image input (image fusion)

Pass an array of source images in image to fuse several inputs into one result — e.g. a reference image + a brand logo, composed by a single prompt.

• OpenAI gpt-image-1 / gpt-image-2: up to 4 source images.
• Google nano-banana / nano-banana-2 / nano-banana-pro: up to 3 source images (earlier images act as primary composition anchors).
• mask cannot be combined with a multi-image array (mask is single-region only) → 400.
• Exceeding a model's image cap → 400 (Model … accepts at most N source images per edit).

REF_B64=$(base64 -i ~/reference-post.png)
LOGO_B64=$(base64 -i ~/brand-logo.png)

curl -X POST https://blockrun.ai/api/v1/images/image2image \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT_HEADER" \
  -d "{
    \"model\": \"google/nano-banana\",
    \"prompt\": \"place the brand logo in the corner, vintage warm palette, no text overlay\",
    \"image\": [
      \"data:image/png;base64,${REF_B64}\",
      \"data:image/png;base64,${LOGO_B64}\"
    ],
    \"size\": \"1024x1024\"
  }"

Same request in OpenAI multipart format (repeated image[]):

curl -X POST https://blockrun.ai/api/v1/images/image2image \
  -H "X-Payment: $PAYMENT_HEADER" \
  -F "model=google/nano-banana" \
  -F "prompt=place the brand logo in the corner, vintage warm palette, no text overlay" \
  -F "image[]=@reference-post.png" \
  -F "image[]=@brand-logo.png" \
  -F "size=1024x1024"

Single-image requests are unchanged — image as a plain string (JSON) or a single image[]/image file (multipart) both work.

Pricing

Edits bill exactly like generations on the same model:

billed = catalog rate for the size × n × 1.05   (5% platform margin on media)
       + $0.001                                 (flat transaction fee, once per call)

The number of source images does not change the price — you pay per output image.

Error Codes

What's next?