Complete Reference

API Reference

Every endpoint, parameter, and response shape for the 1FRX platform. All requests use HTTPS, all responses are JSON.

OpenAPI 3.0 Spec

Import directly into Postman, Insomnia, or any OpenAPI-compatible tool.

↓ Download openapi.yaml Open in Swagger UI ↗

Quick Reference

POST /api/image Generate image from template auth POST /api/pdf-gen Generate PDF document auth POST /api/audio Text to speech via ElevenLabs auth POST /api/screenshot Capture URL screenshot auth POST /api/parse OCR & document intelligence auth POST /api/keys/generate Issue a new API key public POST /api/keys/regenerate Rotate an existing key auth GET /api/health Service health check public POST /api/mcp MCP Streamable HTTP server public

Authentication

Include your API key in the X-1FRX-Key header on every request to a paid endpoint.

X-1FRX-Key: sk_live_your_key_here

Key format: All keys follow the pattern sk_live_<payload>.<signature>. Keys are HMAC-signed and self-validating — no database lookup required. Generate yours at 1frx.com/dashboard.html.

Base URL

https://1frx.com

All endpoints are relative to this base. Every endpoint runs on Vercel Edge Runtime — responses are served from the nearest edge location globally.

Rate Limits

Plan	Requests / Month	Burst Limit
Starter	500	10 req/min
Pro	5,000	60 req/min
Business	25,000	120 req/min
VIP	Unlimited	Unlimited

Rate-limited responses return HTTP 429 with a Retry-After header (seconds).

Status Codes

200

Success — request completed

400

Bad Request — missing or invalid parameter

401

Unauthorized — missing or invalid API key

403

Forbidden — plan does not include this endpoint

429

Too Many Requests — rate limit exceeded

500

Internal Error — upstream service failure

Error response shape

{
  "error": "missing required field: template",
  "status": 400
}

Paid Endpoints

All paid endpoints require the X-1FRX-Key header and a Pro plan or above.

POST /api/image Requires key

Generate a branded image using a built-in template or custom HTML. Rendered at 2× resolution via headless Chrome and uploaded to CDN. Returns a permanent URL.

Request body

Parameter	Type	Required	Description
template	string	required	`ogCard` (1200×630), `socialSquare` (1080×1080), `twitterCard` (800×418), `announcementBanner` (1200×400), or `custom`
data	object	required	Template variables: `title`, `subtitle`, `body`, `cta_text`, `brand_color`, `logo_url`, `background_color`, `text_color`
html	string	optional	Custom HTML string (only for `template: "custom"`)
format	string	optional	`png` (default), `jpeg`, or `webp`
quality	number	optional	JPEG/WebP quality 1–100 (default: 90)
width / height	number	optional	Override default template dimensions in pixels

Example request

{
  "template": "ogCard",
  "data": {
    "title": "Launch Day",
    "subtitle": "AI-powered PDF generation is live",
    "brand_color": "#5ee3ff",
    "background_color": "#070910"
  },
  "format": "png"
}

Response

{
  "url": "https://cdn.1frx.com/images/a3f9b2c1.png",
  "template": "ogCard",
  "width": 1200,
  "height": 630,
  "format": "png",
  "size_bytes": 84320
}

POST /api/pdf-gen Requires key

Generate a PDF document from a built-in template. Rendered via headless Chrome with printBackground: true and uploaded to CDN.

Request body

Parameter	Type	Required	Description
template	string	required	`invoicePdf`, `certificatePdf` (auto-landscape), `reportPdf`, `letterPdf`, or `custom`
data	object	required	Template-specific fields. Invoice: `invoice_number`, `date`, `from_name`, `to_name`, `items[]`. Certificate: `recipient_name`, `course_name`, `issuer_name`. See PDF Generation docs for full field lists.
page_size	string	optional	`A4` (default), `Letter`, `Legal`, `A3`
landscape	boolean	optional	Landscape orientation (auto-true for `certificatePdf`)
margin	string	optional	`none`, `small`, `normal` (default), `large`

Response

{
  "url": "https://cdn.1frx.com/pdfs/b8c21d4e.pdf",
  "template": "invoicePdf",
  "page_size": "A4",
  "landscape": false,
  "pages_est": 1,
  "size_bytes": 142560
}

POST /api/audio Requires key

Convert text to speech using ElevenLabs voices. Audio is uploaded to CDN and the permanent URL is returned.

Request body

Parameter	Type	Required	Description
script	string	required	Text to synthesize
voice_id	string	optional	ElevenLabs voice ID. Default: Rachel (`21m00Tcm4TlvDq8ikWAM`)
model	string	optional	Default: `eleven_multilingual_v2`
format	string	optional	`mp3` (default), `wav`, `opus`, `aac`
stability	number	optional	0–1, default 0.5
similarity	number	optional	0–1, default 0.75
speed	number	optional	0.7–1.2, default 1.0

Response

{
  "url": "https://cdn.1frx.com/audio/c7d38f91.mp3",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "model": "eleven_multilingual_v2",
  "format": "mp3",
  "size_bytes": 248104,
  "duration_est_sec": 15.5
}

POST /api/screenshot Requires key

Capture a screenshot of any public URL via headless Chrome. Supports full-page capture, device emulation, dark mode, and ad blocking.

Request body

Parameter	Type	Required	Description
url	string	required	Public URL to capture
device	string	optional	`desktop` (1280×800, default), `laptop` (1440×900), `tablet` (768×1024), `mobile` (390×844)
format	string	optional	`png` (default), `jpeg`, `webp`
fullPage	boolean	optional	Capture full scrollable page (default: false)
darkMode	boolean	optional	Enable prefers-color-scheme: dark (default: false)
blockAds	boolean	optional	Block common ad networks (default: false)
delay	number	optional	Wait ms before capture (for animations / lazy load)
selector	string	optional	CSS selector — only capture that element

Response

{
  "url": "https://cdn.1frx.com/screenshots/d4e59012.png",
  "width": 1280,
  "height": 800,
  "format": "png",
  "size_bytes": 391200
}

POST /api/parse Requires key

Extract structured data from a document or image using Claude Vision. Returns JSON with document type, confidence score, and extracted fields. Supports optional custom output schema.

Request body

Parameter	Type	Required	Description
file	string	required	Base64-encoded file contents
mimeType	string	required	`application/pdf`, `image/jpeg`, `image/png`, `image/webp`
schema	object	optional	JSON schema defining fields to extract. If omitted, the model auto-detects document type.
hints	string	optional	Plain-English instructions for extraction

Response

{
  "document_type": "invoice",
  "confidence": 0.97,
  "data": {
    "invoice_number": "INV-2024-001",
    "date": "2024-04-16",
    "vendor": "Acme Corp",
    "total": 2800.00,
    "line_items": [
      { "description": "Web Design", "qty": 1, "unit_price": 2500 },
      { "description": "Hosting Setup", "qty": 1, "unit_price": 300 }
    ]
  },
  "warnings": []
}

Key Management

POST /api/keys/generate Public

Issue a new HMAC-signed API key tied to an email address and plan. The key is returned once and emailed — it cannot be retrieved again.

Request body

Parameter	Type	Required	Description
email	string	required	Email address to associate with the key
plan	string	required	`starter`, `pro`, `business`, or `vip`

Response

{
  "key": "sk_live_eyJlbWFpbCI6InlvdUBleG...",
  "email": "you@example.com",
  "plan": "pro",
  "issued_at": "2026-04-16T22:00:00Z"
}

POST /api/keys/regenerate Requires key

Validate the current key (via X-1FRX-Key header) and issue a replacement. The old key is immediately abandoned.

Response

{
  "key": "sk_live_newKeyHere...",
  "email": "you@example.com",
  "plan": "pro"
}

GET /api/health Public

Diagnostic endpoint. Checks all 10 environment variables and runs live connectivity tests against R2, ElevenLabs, and Browserless.

Response

{
  "status": "ok",
  "env": { "ANTHROPIC_API_KEY": "set (108)", "ELEVENLABS_API_KEY": "set (51)" },
  "r2": { "ok": true, "url": "https://cdn.1frx.com/_health/probe-1234.txt" },
  "elevenlabs": { "ok": true, "voices_count": 48 },
  "browserless": { "ok": true, "version": "2.x" }
}

POST /api/mcp Public

MCP Streamable HTTP transport endpoint. Accepts JSON-RPC 2.0 messages and exposes all paid tools to Claude, GPT-4o, and any MCP-compatible agent. See the MCP Server docs for full setup instructions.

Supported methods

Method	Description
initialize	MCP handshake — returns server info and capabilities
tools/list	Returns all available tool definitions with JSON schemas
tools/call	Execute a tool by name with the provided arguments
ping	Keepalive — returns empty result

Code Examples

All examples use the Image Automation endpoint. Replace the endpoint path and body for other APIs.

JavaScript

Python

cURL

const res = await fetch('https://1frx.com/api/image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-1FRX-Key': 'sk_live_your_key_here'
  },
  body: JSON.stringify({
    template: 'ogCard',
    data: { title: 'My Blog Post', brand_color: '#5ee3ff' }
  })
});

const { url } = await res.json();
console.log(url); // https://cdn.1frx.com/images/abc123.png

import requests

response = requests.post(
    'https://1frx.com/api/image',
    headers={'X-1FRX-Key': 'sk_live_your_key_here'},
    json={
        'template': 'ogCard',
        'data': {'title': 'My Blog Post', 'brand_color': '#5ee3ff'}
    }
)

data = response.json()
print(data['url'])  # https://cdn.1frx.com/images/abc123.png

curl -X POST https://1frx.com/api/image \
  -H "X-1FRX-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "ogCard",
    "data": { "title": "My Blog Post", "brand_color": "#5ee3ff" }
  }'

Explore the APIs

Image Automation PDF Generation Audio Screenshot OCR & Parse MCP Server Get your key →