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

Field	Type	Default	Description
html	string	—	HTML to render (required)
width	number	1080	Viewport width (100–3840)
height	number	1350	Viewport height (100–3840)
seek_ms	number	—	Wait ms before capture (for animations)
wait_ready	boolean	true	Wait for `window.__READY`

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

Field	Type	Default	Description
html	string	—	HTML to render (required)
format	string	"A4"	Page format (A4, A3, Letter, Legal)
landscape	boolean	false	Landscape orientation
margin	object	—	Page margins {top, right, bottom, left}
print_background	boolean	true	Include background colors/images

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

Field	Type	Default	Description
html	string	—	HTML to render (required)
width	number	1080	Viewport width (100–3840)
height	number	1350	Viewport height (100–3840)
fps	number	10	Frames per second (1–30)
duration_ms	number	—	Duration in ms (100–30000, required)
format	string	"mp4"	"mp4" or "gif"

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

Field	Type	Description
url	string	Required. Video URL (https only; private/loopback hosts rejected).
format	string	One of `best` (default), `2160p`, `1440p`, `1080p`, `720p`, `480p`, `360p`, `audio`, or a raw yt-dlp format string (e.g. `137+140`).

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 (silueta model).

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

Request

Send as multipart/form-data with a file field:

Field	Type	Description
file	File	Image file (required). JPG, PNG, or WEBP. Max 10 MB.

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

Status	Reason
400	Missing file, wrong Content-Type, or unsupported image format
413	File exceeds 10 MB limit
500	Processing error

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

GET /health

Health check endpoint. No authentication required.

curl https://supaserv.io/health

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