# Pixo Agent API

> Pay-per-call image and PDF processing for AI agents over plain HTTP. No account,
> no API key: each request is paid individually via the x402 protocol (HTTP 402)
> in USDC on Base or Solana. Files are processed in memory and deleted the moment
> the response is sent; nothing is stored. Companion service to https://pixo.tools.

Base URL: https://api.pixo.tools

How to call: POST multipart/form-data with a `file` field. An unpaid request
returns `402 Payment Required` with the exact price on each chain; pay with any
standard x402 client (x402-fetch, the x402 SDKs) and retry with the `X-PAYMENT`
header. PDF prices are per page of the input, quoted after the server counts
pages — recomputed on the paid retry, so quotes are tamper-proof. Failed work
is never charged.

## Machine-readable catalogs

- [OpenAPI 3 schema](https://api.pixo.tools/v1/openapi.json): every endpoint, parameter, and response
- [x402 discovery catalog](https://api.pixo.tools/v1/discovery): live per-endpoint prices, both chains, input/output schemas
- [Health](https://api.pixo.tools/v1/health): liveness

## Image endpoints (flat price per call, USD)

- POST /v1/image/compress — compress or convert (JPEG/PNG/WebP) — $0.005
- POST /v1/image/resize — resize (contain/cover/fill) — $0.005
- POST /v1/image/crop — crop to an exact rectangle — $0.005
- POST /v1/image/rotate — rotate 90/180/270 — $0.005
- POST /v1/image/flip — mirror horizontally/vertically — $0.005
- POST /v1/image/ocr — extract text (Google Gemini; no GIF) — $0.02

Every image endpoint also takes optional `format`/`quality`/`colors` fields:
one paid call can transform, convert, and compress together.

## PDF endpoints (price per input page, USD, unless marked flat)

- POST /v1/pdf/compress — shrink (lossless/balanced/max) — $0.005/page
- POST /v1/pdf/split — split into ranges, ZIP out — $0.005/page
- POST /v1/pdf/merge — merge 2-20 PDFs — $0.005/page (summed over inputs)
- POST /v1/pdf/merge-compress — merge then compress, one call — $0.008/page (bundle)
- POST /v1/pdf/pages — select/reorder/delete/rotate pages — $0.005/page
- POST /v1/pdf/protect — password-protect (AES-256) — $0.005/page
- POST /v1/pdf/unlock — remove a password you supply — $0.02 flat
- POST /v1/pdf/extract — text to JSON with likelyScanned flag — $0.01/page
- POST /v1/pdf/images — embedded images to ZIP of PNGs — $0.01/page
- POST /v1/pdf/markdown — PDF to Markdown (RAG-ready) — $0.02/page
- POST /v1/pdf/render — pages to PNG images, ZIP out (36-300 dpi) — $0.01/page
- POST /v1/pdf/from-markdown — Markdown to PDF — $0.01 flat
- POST /v1/pdf/ocr — OCR a scanned PDF (Google Gemini) — $0.03/page
- POST /v1/pdf/tables — every table to structured JSON (Google Gemini) — $0.03/page
- POST /v1/pdf/structured — your JSON schema to typed JSON (Google Gemini) — $0.04/page

## Limits

- Files up to 50 MB; images up to 40 megapixels
- Merge: up to 20 files / 95 MB total per request
- Gemini-backed PDF endpoints (ocr/tables/structured): up to 30 pages per request (enabled)
- Render: up to 50 pages per request
- Unreadable or password-protected PDFs are rejected before payment

## Privacy

All processing is in-memory and ephemeral; files and filenames are never stored
or logged. The Gemini-backed endpoints (image/ocr, pdf/ocr, pdf/tables,
pdf/structured) are the disclosed exception: they forward file content to
Google for model-based reading. The deterministic pdf/extract and pdf/markdown
paths never leave the server.