# 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)
- Intent: `charge` (one-time per-request payment)
- Currency: `0x20c000000000000000000000b9537d11c60e8b50` (USDC on Tempo)
- Recipient: `0x8009c928c37285dc7e6e0527c3ac36d7a930e4eb`

### Tiered Pricing (per image)

| Model | Tier | Price (USDC) | Base Units |
|---|---|---|---|
| `fal-ai/flux/schnell` | schnell | $0.03 | 30000 |
| `fal-ai/stable-diffusion-v35-large` | sd35 | $0.04 | 40000 |
| `fal-ai/flux/dev` | dev | $0.05 | 50000 |
| `fal-ai/recraft-v3` | recraft | $0.06 | 60000 |
| `fal-ai/hidream-i1-full` | hidream | $0.08 | 80000 |
| `fal-ai/ideogram/v3` | ideogram | $0.08 | 80000 |
| `fal-ai/flux-pro/v1.1` | pro | $0.10 | 100000 |
| `fal-ai/nano-banana-2` | premium | $0.15 | 150000 |
| `fal-ai/nano-banana-pro` | premium | $0.23 | 230000 |

**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.03). 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

## Endpoint

### 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. Options: `fal-ai/flux/schnell` ($0.03, default), `fal-ai/stable-diffusion-v35-large` ($0.04), `fal-ai/flux/dev` ($0.05), `fal-ai/recraft-v3` ($0.06), `fal-ai/hidream-i1-full` ($0.08), `fal-ai/ideogram/v3` ($0.08), `fal-ai/flux-pro/v1.1` ($0.10), `fal-ai/nano-banana-2` ($0.15, premium), `fal-ai/nano-banana-pro` ($0.23, premium)
- `image_size` (string, optional): Output size. Default: `landscape_4_3`. Options: `square_hd`, `square`, `landscape_4_3`, `landscape_16_9`, `portrait_4_3`, `portrait_16_9`
- `num_images` (integer, optional): Number of images, 1-4. Default: 1

**Success response** (200):
```json
{
  "images": [
    {
      "url": "https://...",
      "width": 1024,
      "height": 768,
      "content_type": "image/jpeg"
    }
  ],
  "prompt": "...",
  "model": "fal-ai/flux/schnell",
  "timings": {}
}
```

**Payment challenge** (402):
```json
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Generate an image for 0.03 USDC (schnell tier)"
}
```

## Discovery

- OpenAPI spec: `GET /openapi.json`
- LLM docs: `GET /llms.txt`
- Pricing: `GET /v1/prices`
- Health check: `GET /health`

## Links

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