# Cloudflare API
> Replicate AI models and Cloudflare Browser Rendering via x402/MPP micropayments. All endpoints POST.

## Base URL
https://cloudflare-api.dev

## Auth
x402/MPP payment (USDC on Base, Solana, or Tempo). Use check_endpoint_schema on any endpoint to get its request schema before calling.

---

## Replicate — AI Models (official models only)

### Workflow (read this first)
1. **models/search** to find candidates. Each result has a `category` field (`image` | `video` | `audio` | `text`) — use that to pick the create endpoint, not a guess from the name.
2. **models/get** before running any model. The returned `latest_version.openapi_schema` shows per-parameter types AND descriptions that contain hidden constraints (max audio duration, supported aspect ratios, required formats, etc). Input schemas vary wildly per model — omni-human takes image+audio, sync/lipsync takes video+audio, seedance takes prompt+duration+resolution. Do not guess inputs.
3. **create-{image,video,text}** with `{ "model": "owner/name", "input": {...} }`. Returns `{ id, status }` immediately. Payment settles on submission.
4. **predictions/get** to poll status. Poll every 30–60s — faster wastes requests and may hit Replicate rate limits. Video/audio runs routinely take 1–10 minutes.

### Discovery (free, SIWX)
/api/replicate/models/search — Search official models. Returns owner, name, category, description.
Example: POST /api/replicate/models/search { "query": "flux image generation" }

/api/replicate/models/get — Model details including latest_version.openapi_schema. **Call this before every first run of a model.**
Example: POST /api/replicate/models/get { "owner": "black-forest-labs", "name": "flux-schnell" }

/api/replicate/models/versions — List versions for a specific model
/api/replicate/collections/list — List curated collections
/api/replicate/collections/get — Get models in a collection by slug

### Run models
/api/replicate/predictions/create-image ($0.10) — image generation, editing, upscaling
Example: POST /api/replicate/predictions/create-image { "model": "black-forest-labs/flux-schnell", "input": { "prompt": "a cat wearing a top hat" } }

/api/replicate/predictions/create-video ($1.00) — video generation, editing, animation, lipsync, image-to-video
/api/replicate/predictions/create-audio ($1.00) — text-to-speech, music generation, voice cloning, audio generation
/api/replicate/predictions/create-text ($0.05) — language models, chat, completion, embeddings, speech-to-text

/api/replicate/predictions/get (free, SIWX) — poll prediction status
/api/replicate/predictions/cancel (free, SIWX) — cancel a running prediction

### Important: failures are not refunded
Payment settles when you POST to create-*. If the prediction later fails (status `failed`, upstream error, timeout) you are NOT automatically refunded. **Always call models/get and validate your input against `latest_version.openapi_schema` before submitting** — especially for create-video ($1.00). Constraints like "audio ≤15s" live in parameter `description` fields, not in the top-level schema.

---

## Browser Rendering — Cloudflare headless browser

/api/browser/screenshot — Capture screenshot of any URL ($0.05)
Example: POST /api/browser/screenshot { "url": "https://example.com", "screenshotOptions": { "fullPage": true } }

/api/browser/pdf — Render URL as PDF ($0.05)
Example: POST /api/browser/pdf { "url": "https://example.com" }

/api/browser/markdown — Extract clean Markdown ($0.02)
Example: POST /api/browser/markdown { "url": "https://example.com" }

/api/browser/json — AI-powered structured data extraction ($0.05)
Example: POST /api/browser/json { "url": "https://example.com", "prompt": "Extract all product names and prices" }

/api/browser/scrape — Scrape elements by CSS selector ($0.02)
Example: POST /api/browser/scrape { "url": "https://example.com", "elements": [{ "selector": "h1" }, { "selector": "a" }] }

/api/browser/content — Fetch fully rendered HTML ($0.02)
Example: POST /api/browser/content { "url": "https://example.com" }

/api/browser/links — Extract all links from a page ($0.02)
Example: POST /api/browser/links { "url": "https://example.com", "visibleLinksOnly": true }

All browser endpoints support: cookies, authenticate, userAgent, waitForSelector, gotoOptions.

/api/browser/crawl — Start an async crawl job ($0.10)
Example: POST /api/browser/crawl { "url": "https://example.com/docs/", "limit": 10, "depth": 2, "formats": ["markdown"] }
Returns { "token": "<jwt>" } — use the token to poll for results.

GET /api/browser/crawl/poll?token=<jwt> — Poll crawl results (free, SIWX auth)
Returns crawled pages with markdown/html/json content. Only the wallet that started the crawl can poll.

---

## Images — Cloudflare Images upload + on-the-fly transforms

/api/images/upload — Upload an image by URL ($0.01)
Example: POST /api/images/upload { "url": "https://example.com/photo.jpg" }
Returns { "id": "abc123", "variants": ["https://imagedelivery.net/.../public"], ... }

/api/images/transform — Generate a transformed delivery URL ($0.01)
Example: POST /api/images/transform { "image_id": "abc123", "width": 800, "format": "webp", "quality": 80 }
Returns { "url": "https://imagedelivery.net/.../w=800,format=webp,quality=80", ... }

Supports: width, height, fit (scale-down/contain/cover/crop/pad), quality, format (webp/avif/jpeg/png), gravity (auto/face), rotate, blur, sharpen, brightness, contrast, dpr, metadata.

Workflow: upload once, then generate as many transform URLs as needed. Transforms are cached on CF's edge.