# FrameFetch

> Agent-first API + MCP that turns any social-video URL (YouTube, YouTube Shorts, TikTok, Instagram Reels, Pinterest, Reddit) into metadata, insights, transcript, and parametrically-sampled frames. Pay per call; light calls are sub-cent; a free tier exists; agents can pay with x402 (USDC) without an account.

## Core

- [Get an API key]: `POST https://framefetch.net/v1/keys` — body `{ email }`. Returns `{ key }` (shown once) with a small free credit. Self-serve; no human in the loop.
- [Extract endpoint]: `POST https://framefetch.net/v1/extract` — body `{ url, fields[], frames{}, verbosity }`. `fields` ⊆ `["metadata","insights","transcript","frames"]` (default `["metadata"]`). Returns one JSON object with the requested data; `frames` are time-limited signed image URLs. Auth: `Authorization: Bearer <key>`. Returns 402 when out of credit. Request only what you need — metadata is cheap, transcript/frames cost more.
- [Scoped shortcuts] (same auth/billing, preset fields): `POST /v1/metadata` (metadata+insights), `POST /v1/transcript`, `POST /v1/frames` (needs a `frames` spec). Body just `{ url, ... }`.
- [Buy credits with a card]: `POST /v1/checkout` (Bearer key) -> returns a Stripe Checkout URL (for humans).
- [Top up credits]: `POST https://framefetch.net/v1/topup` — Bearer key + x402. Without payment returns HTTP 402 with x402 payment requirements (USDC); pay and retry with `X-PAYMENT` to add credit. Agents can pay without a human.
- [Platform capabilities]: `GET https://framefetch.net/v1/platforms` — which data each platform supports.
- [Health]: `GET https://framefetch.net/healthz`.
- [MCP]: `POST https://framefetch.net/mcp` — Streamable HTTP MCP server (Bearer key). Tools: `framefetch_extract`, `framefetch_platform_capabilities`.

## Pricing / payment

- Free credit on signup. Pay per call (metadata sub-cent; transcript per-minute; frames per-frame).
- Top up with USDC via x402 (`POST /v1/topup`) — no account or human needed.

## Frames spec

- `mode`: `all` | `every_n` (with `n`) | `fps` (with `fps`, ≤60) | `range` (with `from`,`to`,`fps`)
- `format`: `jpg` | `png` | `webp`; `width`: 16–7680 (downscale)

## Notes

- Supported hosts only (SSRF-guarded): youtube.com, youtu.be, tiktok.com, instagram.com, pinterest.*, reddit.com, redd.it.
- Request only the fields you need — transcript and frames cost more than metadata.
- Errors are JSON `{ "error": { "code", "message", "hint" } }`.