FrameFetch docs

1. Authenticate

Get a key (free $0.05 credit, shown once). No human approval.

curl -X POST https://framefetch.net/v1/keys \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'
# -> { "key": "ff_xxx_yyy", "message": "store this key; it is shown once..." }

Send it as Authorization: Bearer ff_xxx_yyy on every call.

2. Extract

POST /v1/extract — one call, choose your fields.

Body field	Type	Meaning
url	string (required)	The video URL (supported hosts only).
fields	string[]	Any of metadata, insights, transcript, frames. Default ["metadata"].
frames	object	Frame spec (see below). Required if frames is in fields.
verbosity	string	Optional response detail level.

curl -X POST https://framefetch.net/v1/extract \
  -H "Authorization: Bearer ff_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "fields": ["metadata", "transcript", "frames"],
    "frames": { "mode": "fps", "fps": 1, "width": 480 }
  }'

3. Scoped shortcuts

Same auth and billing, with preset fields — for agents that want just one thing.

Endpoint	Returns
POST /v1/metadata	metadata + insights
POST /v1/transcript	transcript only
POST /v1/frames	frames only (needs a frames spec)

curl -X POST https://framefetch.net/v1/transcript \
  -H "Authorization: Bearer ff_xxx_yyy" -H "Content-Type: application/json" \
  -d '{ "url": "https://www.tiktok.com/@user/video/123" }'

4. Frames spec

Field	Values
mode	all · every_n (+n) · fps (+fps, ≤60) · range (+from,to,fps)
format	jpg · png · webp
width	16–7680 px (downscale — lower = cheaper)

Up to 1000 frames per call. Frames return as time-limited signed image URLs.

5. Response shape

{
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=...",
  "metadata": { "title": "...", "uploader": "...", "durationSec": 19, "uploadDate": "..." },
  "insights": { "views": 1234, "likes": 56, "comments": 7 },
  "transcript": { "text": "...", "source": "whisper" },
  "frames": [ { "index": 1, "url": "https://.../frame_00001.jpg", "tSec": 0 } ],
  "cost": { "totalMicros": 2000, "breakdownMicros": { "metadata": 150, "transcript": 0, "frames": 0, "proxy": 0 } }
}

Only requested fields are present. cost is always included (micro-USD; 1,000,000 = $1).

6. Errors

All errors are JSON: { "error": { "code", "message", "hint" } }. Codes are stable so agents can self-correct.

HTTP	code	Meaning
400	INVALID_PARAMS · INVALID_URL · UNSUPPORTED_HOST · OVER_LIMIT	Bad request / unsupported video / over a cap
401	UNAUTHORIZED	Missing/invalid key
402	PAYMENT_REQUIRED	Out of credit — top up and retry
429	RATE_LIMITED	Slow down (see Retry-After)
500	EXTRACTION_FAILED · INTERNAL	Server-side; safe to retry

7. MCP (for agents)

Streamable HTTP MCP server at POST https://framefetch.net/mcp (send your Bearer key). Tools:

Tool	Purpose
framefetch_extract	Extract metadata/transcript/frames from a URL
framefetch_platform_capabilities	What each platform supports

Example MCP client config (Claude Desktop / Cursor style):

{
  "mcpServers": {
    "framefetch": {
      "url": "https://framefetch.net/mcp",
      "headers": { "Authorization": "Bearer ff_xxx_yyy" }
    }
  }
}

8. Paying with x402 (no account)

POST /v1/topup without payment returns 402 with x402 requirements (USDC on Base). Pay and retry with the X-PAYMENT header to add 1 USDC = $1 credit. Designed for autonomous agents — no signup, no human.

9. Platforms

YouTube · YouTube Shorts · TikTok · Instagram Reels · Pinterest · Reddit. Capability matrix: GET /v1/platforms. Per-platform guides: YouTube · TikTok · Instagram · Reddit · Pinterest.