Image Generation API

Generate images using GPT Image (including ChatGPT Images 2.0), Google Nano Banana, CogView-4, or xAI Grok Imagine.

Endpoint

POST https://blockrun.ai/api/v1/images/generations

Request

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

Parameters

Available Models

CogView-4 Sizes

zai/cogview-4 supports flexible sizes (multiples of 16, max 1440×1440):

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) and starts generation.
2. Fast path (≤30s inline window — most models): generation finishes inline. The gateway settles the payment and returns 200 with the standard { created, data: [...] } body below. This is the only moment a fast-path call is charged.
3. Slow path (>30s — e.g. 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.
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.063000", "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 responses

• 202 running: { id, object, status: "queued" | "in_progress", model, payment_status: "verified" }
• 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 failed (not charged): { id, object, status: "failed", model, error, payment_status: "not_charged" }

Response

{
  "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.015000", "currency": "USD" },
  "payment": { "status": "settled", "tx_hash": "0x…", "network": "base" }
}

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

Error Codes

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)

What's next?