Image Generation API

Generate images using GPT Image (including ChatGPT Images 2.0), Google Nano Banana (including Nano Banana 2 and Pro), ByteDance Seedream 5.0 Pro, CogView-4, or xAI Grok Imagine.

Endpoint

POST https://blockrun.ai/api/v1/images/generations
GET  https://blockrun.ai/api/v1/images/generations/{id}   # poll (async slow path only)
GET  https://blockrun.ai/api/v1/images/models              # catalog + per-size prices, free

Request

{
  "model": "google/nano-banana",
  "prompt": "A futuristic city at sunset",
  "size": "1024x1024",
  "n": 1
}

The body must be application/json. A body that is not valid JSON returns 400 { "error": "Invalid JSON", ... }; a body that fails validation returns 400 { "error": "Invalid request body", "details": [...] } with the per-field issues.

Parameters

Unknown fields (for example OpenAI's quality, style, response_format) are ignored, not rejected.

Available Models

Prices are what the 402 challenge quotes and what is billed for one image at that size: the catalog rate + 5% + the flat $0.001 transaction fee. See Pricing for the formula and every size.

GET /api/v1/images/models returns the same catalog with pricing.sizes[] per model (catalog rates, before margin and fee). openai/dall-e-3 was removed from the catalog and now returns the unknown-model 400.

Seedream 5.0 Pro Sizes

bytedance/seedream-5-pro is ByteDance's flagship image model (up to 4K-class resolution). Pricing is by output pixel count — sizes at or below ~2.36M pixels bill $0.04825, larger sizes bill $0.0955 (catalog $0.045 / $0.09 + 5% + $0.001):

Seedream 5.0 Pro generations take ~2 minutes — calls always resolve through the async 202 + poll flow described below, and you are only charged when the image completes.

CogView-4 Sizes

zai/cogview-4 accepts exactly these sizes (any other value returns 400):

How it works — hybrid sync/async flow & settlement

This endpoint is hybrid: fast generations complete synchronously, slow ones switch to an async job you poll. The split is purely by elapsed time:

1. POST /v1/images/generations with an x-payment (or PAYMENT-SIGNATURE) header. The gateway verifies the payment authorization (no USDC moves yet), claims the authorization's nonce so it cannot be reused, creates a job, and starts generation.
2. Fast path (≤30s inline window — most models): generation finishes inline. The gateway mirrors the image to durable storage, settles the payment and returns 200 with the standard { id, created, data: [...] } body below. This is the only moment a fast-path call is charged.
3. Slow path (>30s — bytedance/seedream-5-pro always, openai/gpt-image-2 under load): the gateway returns 202 with an async job envelope { id, status: "queued", poll_url, price, payment_status: "verified" }. No USDC has moved. Generation keeps running in the background — the upstream call for openai/gpt-image-2 is allowed up to 600s.
4. GET {poll_url} — poll every 2–5s with an x-payment header signed by the same wallet (a fresh signature works; the gateway enforces wallet binding, not signature byte-equality; with no header it returns a normal x402 402 challenge so clients can re-sign automatically). While the job runs you get 202 (status: queued | in_progress). When it finishes you get 200 with the image URLs, and that is the moment you are charged — settlement happens exactly once, on the first poll that observes status: "completed".

Async job envelope (202)

{
  "id": "img_8f3a…",
  "object": "image.generation.job",
  "status": "queued",
  "model": "openai/gpt-image-2",
  "size": "1024x1024",
  "n": 1,
  "price": { "amount": "0.064000", "currency": "USD" },
  "payment_status": "verified",
  "created": 1706000000,
  "poll_url": "/api/v1/images/generations/img_8f3a…",
  "poll_instructions": "…"
}

status enum: queued → in_progress → completed | failed. poll_url is a path — prefix it with the origin you posted to.

Poll responses

• 202 running: { id, object, status: "queued" | "in_progress", model, payment_status: "verified", note }
• 200 completed (charged here): the standard body below plus price: { amount, currency } and payment: { status: "settled", tx_hash, network }, with PAYMENT-RESPONSE and X-Payment-Receipt (on-chain tx hash) headers.
• 200 completed, already settled (not charged again): same body with payment.status: "already_settled".
• 200 failed (not charged): { id, object, status: "failed", model, error, payment_status: "not_charged", note }
• 402 no header: a fresh x402 challenge for this job (job_id, model, price in the body; requirements in the headers) — sign with the original wallet and retry.
• 402 settlement failed: { error: "Payment settlement failed", details, note } — the image is ready but the authorization could not be settled; retry the poll, and re-sign if the authorization has expired.
• 403 payer mismatch: { error: "Payment payer mismatch" } — the presenting wallet is not the one that submitted the job.
• 404 job not found: { error: "Job not found" } — expired or never created.

Response

{
  "id": "img_8f3a…",
  "created": 1706000000,
  "data": [
    {
      "url": "https://blockrun.ai/api/media/media/images/2026/04/17/<id>.jpg",
      "source_url": "https://<upstream-host>/...",
      "backed_up": true,
      "revised_prompt": "..."
    }
  ],
  "price": { "amount": "0.016750", "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 for local use)

ClawRouter handles x402 payments automatically. Start it with openclaw gateway start, then call localhost:8402 directly.

curl -X POST http://localhost:8402/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"zai/cogview-4","prompt":"a futuristic city at night","size":"1024x1024"}'

Open the returned URL directly:

URL=$(curl -s -X POST http://localhost:8402/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana","prompt":"your prompt here","size":"1024x1024"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data'][0]['url'])")

open "$URL"   # macOS
xdg-open "$URL"   # Linux

Direct API

Pricing

Every price below is the amount quoted in the 402 challenge (price.amount) and billed in USDC:

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

n multiplies the margined rate; the transaction fee is charged once per call, not per image. The catalog rates themselves are published by GET /api/v1/images/models.

Error Codes

402 responses

The unpaid 402 is a normal x402 challenge: the signable requirements live in the X-Payment-Required / PAYMENT-REQUIRED / WWW-Authenticate headers (base64 JSON, x402Version: 2, maxTimeoutSeconds: 600), mirrored at the top of the body (x402Version, accepts) for clients that only read the body; the rest of the body is informational.

{
  "x402Version": 2,
  "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "53500", "asset": "0x8335…", "payTo": "0x…", "maxTimeoutSeconds": 600 }],
  "error": "Payment Required",
  "message": "This endpoint requires x402 payment",
  "price": { "amount": "0.053500", "currency": "USD", "pricePerImage": 0.05, "totalImages": 1 },
  "generation_info": { "generation_time": "~10s-10min upstream depending on model and prompt complexity", "flow": "hybrid", "note": "..." },
  "paymentInfo": { "network": "base", "asset": "USDC", "x402Version": 2 }
}

price.amount is the billed total; pricePerImage is the catalog rate before margin and fee.

When a payment header is present but rejected, the body is { "error": "Payment verification failed", "code", "message"?, "details" } and code is machine-readable:

A 402 { "error": "Payment settlement failed" } (with a PAYMENT-RESPONSE header) means verification passed but settlement did not; on the fast path nothing was billed, on the poll path retry the poll.

Model Selection Guide

OpenAI Compatibility

This endpoint is compatible with OpenAI's Images API:

from openai import OpenAI

client = OpenAI(
    base_url="https://blockrun.ai/api/v1",
    api_key="unused"  # x402 payment handled via header
)

response = client.images.generate(
    model="zai/cogview-4",
    prompt="A futuristic city",
    size="1024x1024"
)
print(response.data[0].url)

The extra id, price and payment fields are additive — OpenAI clients ignore them. The OpenAI SDK's bearer key does not pay: you still need an x402 header, so pair it with a client that signs one (BlockRun SDKs, ClawRouter).

What's next?