# PixelPay

> PixelPay — AI image generation API monetized via MPP (Machine Payments Protocol).

## Overview

PixelPay lets you generate images from text prompts using fal.ai models. Each request is paid per-use through the Machine Payments Protocol (MPP) using Tempo blockchain with USDC stablecoins.

No API keys needed. Just pay per request.

## Payment

- Protocol: MPP (Machine Payments Protocol)
- Method: `tempo` (Tempo blockchain, chain ID 4217)
- Intent: `charge` (one-time per-request payment)
- Currency: `0x20c000000000000000000000b9537d11c60e8b50` (USDC on Tempo)
- Recipient: `0xf48c6E46358652fC77462d56d609B8bC7f4ba82e`
- Fee payer: Server pays gas (you only pay USDC amount)

### Tiered Pricing (per image)

| Model | Tier | Price (USDC) | Base Units |
|---|---|---|---|
| `fal-ai/flux/schnell` | schnell | $0.029 | 29000 |
| `fal-ai/flux/dev` | dev | $0.049 | 49000 |
| `fal-ai/recraft-v3` | recraft | $0.059 | 59000 |
| `fal-ai/hidream-i1-full` | hidream | $0.079 | 79000 |
| `fal-ai/ideogram/v3` | ideogram | $0.079 | 79000 |
| `fal-ai/flux-pro/v1.1` | pro | $0.099 | 99000 |
| `fal-ai/nano-banana-2` | premium | $0.14 | 140000 |
| `fal-ai/nano-banana-pro` | premium | $0.19 | 190000 |

**Premium models** (`fal-ai/nano-banana-2`, `fal-ai/nano-banana-pro`) require wallet payment — not available in free demo.

Default model: `fal-ai/flux/schnell` ($0.029). Price is determined by the `model` field in your request.

## Payment Flow

1. `POST /v1/images/generate` with your prompt and model (no auth header)
2. Receive `402 Payment Required` with `WWW-Authenticate: Payment ...` challenge (amount varies by model)
3. Sign a Tempo transaction transferring the required USDC to the recipient
4. Retry the same request with `Authorization: Payment <base64url-credential>`
5. Receive `200 OK` with generated images and a `Payment-Receipt` header

## Endpoints

### POST /v1/images/generate

Generate an image from a text prompt.

**Request body** (JSON):
- `prompt` (string, required): Text describing the image to generate
- `model` (string, optional): Model ID. Default: `fal-ai/flux/schnell`
- `image_size` (string, optional): Output size. Default: `landscape_4_3`. Options: `square_hd`, `square`, `landscape_4_3`, `landscape_16_9`, `portrait_4_3`, `portrait_9_16`, `widescreen_21_9`
- `num_images` (integer, optional): 1-4 images. Default: 1
- `image_urls` (string or array, optional): Reference image(s) for img2img. Supported by Nano Banana 2/Pro, Recraft V3, FLUX Dev
- `style` (string, optional): Style preset: `anime`, `cinematic`, `vintage`, `noir`, `cyberpunk`, `watercolor`, `oil-painting`, `pixel-art`, `minimalist`, `pop-art`
- `enhance` (boolean, optional): Auto-enhance prompt. Default: false
- `negative_prompt` (string, optional): Things to avoid (e.g. "blur, watermark")
- `seed` (integer, optional): For reproducible results

**Example request:**
```
POST /v1/images/generate
Content-Type: application/json

{"prompt": "a serene mountain landscape at sunset", "model": "fal-ai/flux/schnell"}
```

**402 response (pay this):**
```
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="pixelpayapi.com", method="tempo", intent="charge", request="<base64url>", expires="..."

{"status": 402, "detail": "Generate an image for 0.029 USDC (schnell tier)"}
```

**200 response (after payment):**
```json
{
  "images": [{"url": "https://fal.media/files/...", "width": 1024, "height": 768, "content_type": "image/jpeg"}],
  "prompt": "a serene mountain landscape at sunset",
  "model": "fal-ai/flux/schnell",
  "seed": 1234567890
}
```

### GET /v1/models

List all available models with capabilities and pricing.

### GET /v1/prices

Get current pricing for all models.

### POST /v1/validate

Validate a prompt before paying. Returns estimated cost and model info.

**Request:** `{"prompt": "...", "model": "fal-ai/flux/schnell"}`
**Response:** `{"valid": true, "prompt": "...", "model": "fal-ai/flux/schnell", "tier": "schnell", "price": "29000", "price_usd": "0.029", "premium": false, "surge_multiplier": 1}`

### GET /v1/styles

List available style presets.

### POST /v1/images/upscale

Upscale an image 2x using fal.ai creative-upscaler.

**Request:** `{"image_url": "https://..."}`

### GET /v1/gallery

Public image gallery (JSON). Returns recent community-generated images.

### GET /v1/history/:wallet

Per-wallet generation history (last 100 entries).

### GET /health

Health check endpoint.

## Discovery

- OpenAPI spec: `GET /openapi.json`
- Agent instructions: `GET /agents.txt`
- LLM docs: `GET /llms.txt` (this file)
- Well-known: `GET /.well-known/mpp.json`

## Links

- Website: https://pixelpayapi.com
- MPP spec: https://mpp.dev
- fal.ai: https://fal.ai
- Tempo docs: https://docs.tempo.xyz