Paid Image API

Pay-per-request AI image generation service powered by Tempo Machine Payments Protocol (MPP). No API keys, no subscriptions — just pay and generate.

Live on Mainnet: paid-image-api.vercel.app

---

What is this?

Paid Image API is a production-ready MPP service that lets AI agents and humans generate images by paying USDC per request on the Tempo blockchain. Built with Next.js, deployed on Vercel, and accepting real payments on Tempo Mainnet.

The service demonstrates how any developer can monetize an API endpoint using the Machine Payments Protocol — no Stripe dashboard, no billing accounts, no signup flows.

---

How It Works

Client sends request
        ↓
Server returns 402 + Payment Challenge
        ↓
Client pays USDC on Tempo (auto-handled by mppx/tempo CLI)
        ↓
Server verifies payment on-chain
        ↓
Server returns generated image + Receipt

---

Endpoints

Endpoint	Method	Price	Description
/api/health	GET	Free	Service status & pricing info
/api/generate	POST	$0.05	Generate an AI image from text prompt
/api/gallery	GET	$0.01	Browse generated images

---

Quick Start

As a Client (Pay & Use)

# Install Tempo CLI
curl -fsSL https://tempo.xyz/install | bash

# Login & fund wallet
tempo wallet login
tempo wallet fund

# Generate an image (pays $0.05 USDC)
tempo request -X POST \
  --json '{"prompt":"cyberpunk cityscape at night"}' \
  https://paid-image-api.vercel.app/api/generate

As a Developer (Deploy Your Own)

# Clone & install
git clone https://github.com/cepuyut/paid-image-api.git
cd paid-image-api
npm install

# Set environment variables
cp .env.example .env.local
# Edit .env.local with your wallet address and secret key

# Run locally
npm run dev

# Deploy to Vercel
vercel --prod

---

Environment Variables

Variable	Description
MPP_RECIPIENT	Your Tempo wallet address (receives payments)
MPP_CURRENCY	USDC contract on Tempo Mainnet: 0x20c000000000000000000000b9537d11c60e8b50
MPP_SECRET_KEY	Random secret for signing payment challenges (NOT your wallet private key)

Important: MPP_SECRET_KEY should be a random base64 string generated with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

---

Tech Stack

• Framework: Next.js 16 (App Router)
• Payments: mppx SDK (mppx/nextjs)
• Blockchain: Tempo Mainnet (Chain ID: 4217)
• Currency: USDC on Tempo
• Deployment: Vercel
• Image Model: Flux Dev (via fal.ai proxy)

---

Architecture

┌─────────────┐     HTTP 402      ┌──────────────────┐
│             │  ◄──────────────  │                  │
│  AI Agent   │                   │  Paid Image API  │
│  or Client  │  Pay USDC +      │  (Next.js on     │
│             │  Retry Request    │   Vercel)        │
│             │  ────────────►   │                  │
└─────────────┘                   └──────┬───────────┘
                                         │
                    Verify payment       │
                    on-chain             │
                                         ▼
                                  ┌──────────────┐
                                  │    Tempo      │
                                  │   Mainnet     │
                                  │  (Chain 4217) │
                                  └──────────────┘

---

Example Response

{
  "success": true,
  "image": {
    "id": "781d3934-2710-4ddd-9572-44287202f9b8",
    "prompt": "sunset over mountains",
    "url": "https://picsum.photos/seed/sunset/800/600",
    "model": "flux-dev",
    "created_at": "2026-03-23T23:51:26.241Z"
  }
}

---

Pricing Philosophy

Micropayments on Tempo cost ~$0.001 in gas fees, making sub-dollar pricing viable. This service charges:

• $0.05 per image generation — covers AI compute costs with margin
• $0.01 per gallery view — low friction for browsing

No minimum spend, no monthly fees, no rate limits tied to billing tiers. Pay exactly for what you use.

---

Lessons Learned

Building this service from scratch taught several key insights about MPP development:

1. secretKey is NOT your wallet private key — it's a random secret for signing challenges. Generate it with crypto.randomBytes(32).
2. Mainnet USDC address differs from testnet PathUSD — Mainnet: 0x20c000000000000000000000b9537d11c60e8b50, Testnet: 0x20c0000000000000000000000000000000000000.
3. Tempo handles gas natively in stablecoins — no need for a separate gas token.
4. mppx middleware makes integration trivial — the entire payment logic is ~10 lines of code.

---

Built With

This project was built as part of the Tempo MPP VibeCoding Course, going from zero to production mainnet deployment.

---

Links

• Tempo Docs
• MPP Protocol
• Tempo Explorer
• mppx SDK

---

Author

@fatitihlara — Web3 builder & content creator.

---

License

MIT