DEV Community

Cover image for How I Built a Screenshot API That Doesn't Suck
Namor Nimash
Namor Nimash

Posted on

How I Built a Screenshot API That Doesn't Suck

#webdev #playwright #api #opensource

How I Built a Screenshot API That Developers Can Actually Trust

After spending too many nights babysitting headless Chrome, I stopped trying to make a fragile stack behave and started building something simpler.

This is the story of SnapForge — a screenshot & PDF API for developers who want reliable rendering without turning browser orchestration into a second job.

The Problem

Every time I tried to build screenshot infrastructure myself, I ran into the same set of problems:

  • Too much browser baggage — heavyweight installs, messy dependencies, and too many moving parts.
  • Random rendering failures — timeouts, stuck processes, and pages that worked fine until they suddenly didn’t.
  • Operational overhead — instead of shipping product features, I was debugging browser lifecycle issues.
  • Hosted tools that felt expensive too early — fine at low volume, but hard to justify once usage starts growing.

I didn’t want a giant DIY browser farm, and I didn’t want to be locked into a black-box service either.

I wanted something in the middle: predictable, self-hostable, and simple enough that a small team could actually run it.

The Approach

SnapForge is built around a few decisions that trade a bit of theoretical efficiency for a lot more predictability:

  1. Fresh browser context per job — each render starts clean, which makes failures easier to isolate and avoids the “what state is Chrome in now?” problem.
  2. Async-first workflow — you submit a job, get an ID back immediately, and handle completion through polling or a webhook.
  3. Docker-first deployment — if you want to self-host it, getting started should feel like launching an app, not assembling a browser lab.

That design is not the most clever possible version of a rendering API.

It is the version I would actually trust to run in production.

Architecture 

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │───> │  FastAPI     │────>│  Playwright │
│  (curl, JS) │     │  + Queueing  │     │   Chromium  │
└─────────────┘     └──────────────┘     └─────────────┘
                           ↓
                    ┌──────────────┐
                    │   Webhook    │
                    │   Callback   │
                    └──────────────┘
Enter fullscreen mode Exit fullscreen mode
  • FastAPI handles the API layer and request lifecycle.
  • Concurrency limits keep the service from overcommitting CPU and memory under load.
  • Background processing lets jobs finish outside the request/response path.
  • Playwright launches a fresh browser context, renders the page, saves the result, and exits cleanly.

There are faster ways to squeeze more throughput out of browser automation.

This setup is optimized less for benchmark screenshots and more for sane operations.

The API (Live Demo)

The public demo API below is rate-limited to 5 requests per day per IP.

It runs on a temporary public demo endpoint, so the URL may change over time.

1. Submit a screenshot job 

curl -X POST https://ministers-just-levy-groups.trycloudflare.com/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "full_page": true}'
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "id": "750d77e5-e4e6-4a3b-a36f-570a7d323e96",
  "status": "pending",
  "type": "screenshot",
  "url": "https://example.com/"
}
Enter fullscreen mode Exit fullscreen mode

2. Check job status 

curl https://ministers-just-levy-groups.trycloudflare.com/jobs/750d77e5-e4e6-4a3b-a36f-570a7d323e96
Enter fullscreen mode Exit fullscreen mode

When the job is done:

{
  "status": "done",
  "result_url": "/files/750d77e5-e4e6-4a3b-a36f-570a7d323e96.png"
}
Enter fullscreen mode Exit fullscreen mode

3. Download the file 

curl -o screenshot.png \
  https://ministers-just-levy-groups.trycloudflare.com/files/750d77e5-e4e6-4a3b-a36f-570a7d323e96.png
Enter fullscreen mode Exit fullscreen mode

Generate a PDF 

curl -X POST https://ministers-just-levy-groups.trycloudflare.com/pdf \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
Enter fullscreen mode Exit fullscreen mode

The API is intentionally boring in a good way: submit a job, track it, download the result, move on.

Self-Hosting in 30 Seconds 

git clone https://github.com/NamorNimash/snapforge-api.git
cd snapforge-api
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

That’s it.

You get a local API on http://localhost:8000, predictable deployment, and no extra ceremony just to make a browser render a page.

Pricing

Plan Price Screenshots PDFs
Open Source Free Unlimited (self-hosted) Unlimited
Cloud Early Bird $20/mo 10,000 5,000
Scale $100/mo 100,000 50,000

The open-source version stays free for teams that want full control.

The hosted plans are for people who want the API without thinking about browser workers, queue limits, uptime, or cleanup jobs.

What’s Next

  • Batch jobs for large screenshot runs
  • Better PDF layout controls
  • SDKs for Python, JavaScript, and Go
  • CI-friendly integrations for automated captures
  • More rendering options for authenticated and dynamic pages

The scope is staying narrow on purpose.

It makes more sense to make screenshot and PDF generation dependable first, then expand from there.

Try It

Built by a developer who got tired of fighting browser processes and just wanted screenshots to work.

Top comments (0)