API Reference

Documentation

Everything you need to render HTML to pixels.

Authentication

All /render endpoints require a Bearer token:

curl -X POST https://supaserv.io/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'

Your API key is provided when you join the beta. Keep it secret — it authenticates all requests.

POST /render

Render HTML to a PNG screenshot.

Request Body

Example

curl -X POST https://supaserv.io/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"background:#000;color:#fff;padding:40px\">Hello World</div>",
    "width": 1080,
    "height": 1080
  }' \
  --output screenshot.png

Returns: image/png

POST /render/pdf v1 · Chromium

Render HTML to a PDF document using the Chromium engine. Also available as /render/pdfv1.

Request Body

Example

curl -X POST https://supaserv.io/render/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Invoice #42</h1><p>Total: EUR 99.00</p>",
    "format": "A4",
    "print_background": true
  }' \
  --output invoice.pdf

Returns: application/pdf

POST /render/pdfv2 v2 · WeasyPrint

Print-ready PDF rendering with CMYK, ICC profiles, bleed, trim marks, and PDF/X-4 support. Powered by WeasyPrint.

Full CSS Paged Media support. Falls back to Chromium if WeasyPrint is unavailable.

Full PDF v2 documentation →

Quick Example

curl -X POST https://supaserv.io/render/pdfv2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Print Flyer</h1>",
    "format": "A4",
    "color_mode": "cmyk",
    "bleed": "3mm",
    "trim_marks": true
  }' \
  --output flyer-print.pdf

Returns: application/pdf

POST /render/video

Capture animated HTML as MP4 or GIF.

Request Body

Example

curl -X POST https://supaserv.io/render/video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div id=\"anim\">...</div>",
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "duration_ms": 5000,
    "format": "mp4"
  }' \
  --output animation.mp4

Returns: video/mp4 or image/gif

Limit: max 900 frames total (fps × duration). Reduce FPS or duration if exceeded.

POST /render/youtube NEW

Download a video as MP4 from YouTube or any of ~1000 sites supported by yt-dlp (Vimeo, TikTok, Twitter/X, Twitch, …).

Request

List available formats

Add ?info=true to inspect metadata + every available stream without downloading:

curl -X POST "https://supaserv.io/render/youtube?info=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/oc6RV5c1yd0"}'

Returns application/json: { id, title, uploader, duration_s, thumbnail, formats: […] }

Download

curl -X POST https://supaserv.io/render/youtube \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/oc6RV5c1yd0","format":"1080p"}' \
  --output video.mp4

Returns: video/mp4 (or audio/mp4 for format=audio).

Limits & long videos

Default max duration: 30 minutes (worker-side, overridable via YTDLP_MAX_DURATION_S env).

Videos longer than 3 minutes return 503 with a worker_endpoint hint — call the worker directly to bypass the gateway timeout:

curl -X POST https://supaserv-worker.fly.dev/youtube \
  -H "Authorization: Bearer WORKER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"...","format":"best"}' \
  --output video.mp4

Note: respect each platform’s ToS and applicable copyright. Self-hosted means you own the compliance choice.

POST /render/rembg NEW

Remove background from an image. Returns a transparent PNG. Powered by rembg (u2net model) with edge refinement.

Best suited for images with white or light backgrounds (product photos, headshots, logos).

Request

Send as multipart/form-data with a file field. Tune aggressiveness with the optional X-Force header (Low / Medium / High):

Example

curl -X POST https://supaserv.io/render/rembg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  --output cutout.png

Returns: image/png (RGBA with transparent background)

Errors

Performance: ~3s per image (warm). First request after deploy may take longer.

POST /render/pdf2text NEW

Extract text from a PDF — or let Claude read it and hand back structured JSON. Text is pulled with PyMuPDF; optional flags add vision OCR and document intelligence.

Request

Send as multipart/form-data with a file field. Behaviour is controlled by query flags:

Example — invoice to JSON

curl -X POST "https://supaserv.io/render/pdf2text?analyze=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Returns: application/json

// with ?analyze=true — detected fields live under "document"
{
  "method": "analyze",
  "summary": "...",
  "pages": 1,
  "document": {
    "type": "invoice",
    "language": "de",
    "confidence": 0.98,
    "invoice_number": "2026-0420",
    "total": 678.30,
    "currency": "EUR",
    "line_items": [ /* description, quantity, unit_price, total, vat_rate */ ],
    "tax_details": [ /* rate, base, amount */ ]
  }
}

Flags also work as headers (X-Analyze, X-Llm, X-Visual). Without any flag it returns plain extracted text + page count. Analysis uses Claude via the worker — rate limited to 10/min.

GET /health

Health check endpoint. No authentication required.

curl https://supaserv.io/health

// Response
{
  "status": "ok",
  "service": "supaserv",
  "version": "0.2.0",
  "backend": "worker"
}