Skip to content

image-editing.md

Latest commit

 

History

History
160 lines (123 loc) · 4.17 KB

image-editing.md

File metadata and controls

160 lines (123 loc) · 4.17 KB

Image Editing API (img2img)

Edit existing images using AI inpainting — pass a source image and describe what to change.

Endpoint

Network URL
Base https://blockrun.ai/api/v1/images/image2image
Solana https://sol.blockrun.ai/api/v1/images/image2image 
POST https://blockrun.ai/api/v1/images/image2image       # Base
POST https://sol.blockrun.ai/api/v1/images/image2image    # Solana

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

Parameter Type Required Description
model string No Model to use (default: openai/gpt-image-1)
prompt string Yes Description of edits to make
image string Yes Source image as base64 data URI (data:image/png;base64,...)
mask string No Mask image as base64 data URI (white = area to edit)
size string No Output size (default: 1024x1024)
n integer No Number of images to generate (default: 1)

Supported Models

Model ID Provider Sizes Pricing
openai/gpt-image-1 OpenAI 1024x1024, 1536x1024, 1024x1536 $0.02-0.04

Response

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A photo with the background changed to..."
    }
  ]
}

Response Fields

Field Type Description
created integer Unix timestamp
data array Array of edited images
data[].url string URL to edited image
data[].revised_prompt string Expanded prompt

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 defines which parts of the image to edit:

  • White pixels = areas to edit (AI generates new content here)
  • Black pixels = areas to keep unchanged

If no mask is provided, the AI will edit the entire image based on the prompt.

Pricing

Prices include 5% BlockRun margin:

Model Size Price
GPT Image 1 1024x1024 $0.021
GPT Image 1 1536x1024 $0.042
GPT Image 1 1024x1536 $0.042

Error Codes

Code Description
400 Invalid request (bad image format, unsupported model, invalid size)
402 Payment required
429 Rate limit exceeded
500 Server error
504 Image editing timed out

Links