SÚGÓ › Felhő tárhely

Screenshot API — automatikus PNG/JPEG bármilyen URL-ről

A /api/screenshot végpont a Cloudflare Browser Rendering futtatókörnyezetét használja, hogy bármilyen publikus URL-ről egy GET-kérésre PNG/JPEG snapshot-ot adjon. PAT-tel hitelesítve, R2-ben cache-elve, plan-aware havi-kvótával.

A PromNET Screenshot API egy egyszerű, GET-alapú végpont, amellyel bármilyen publikus URL-ről PNG vagy JPEG snapshot-ot kérhetsz. A háttérben a Cloudflare Browser Rendering futtatókörnyezete dolgozik — nincs saját Puppeteer-üzemeltetés, nincs Chromium-update, csak egy HTTP-kérés.

Mire jó?

• Social-card auto-generálás — minden új blog-cikkhez vagy projekt-oldalhoz preview-kép.
• Status-page mentés — hivatkozni tudsz arra, hogy egy adott pillanatban hogyan nézett ki egy oldal.
• Visual regression-test — két verzió között diff.
• SaaS dashboard preview — third-party site előnézet a saját app-odban.
• Marketplace listings — termék/szolgáltatás-oldalakról automatikus thumbnail.

Token-szerzés

A /app/profil oldalon az API tokenek szekcióban tudsz Personal Access Token-t generálni. Adj nevet, válassz scope-okat, opcionálisan állíts lejáratot. A token-string csak generáláskor látszik egyszer — másold le rögtön a .env-be vagy a CI-titkok közé.

promnet_pat_a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1

Megjegyzés: Jelenleg a Screenshot API minden érvényes PAT-tel hívható, scope nem szükséges. Egy későbbi sprintben jön a screenshot:run scope.

Alapvető használat (curl)

export PROMNET_TOKEN="promnet_pat_..."

curl -H "Authorization: Bearer $PROMNET_TOKEN" \
  "https://promnet.hu/api/screenshot?url=https://example.com" \
  --output example.png

Ez 1200×630 PNG-t ad vissza. A response-fejlécekből látod a kvóta-állapotot:

HTTP/2 200
content-type: image/png
cache-control: public, max-age=604800
x-screenshot-cache: MISS
x-screenshot-hash: 7f3a4b...
x-screenshot-quota-used: 12
x-screenshot-quota-total: 100

Paraméterek

Cache-stratégia

A response-byte-ok bekerülnek egy belső R2-bucketbe a paraméter-hash (URL + width + height + format) alapján. A cache 7 napig él. Ha ugyanolyan paraméterekkel kéred újra, a cache-ből szolgáljuk ki — nem fogyasztja a havi-kvótádat és <100 ms alatt visszajön.

x-screenshot-cache: HIT   ← cache-ből, ingyen
x-screenshot-cache: MISS  ← valódi browser-render, kvóta-fogyasztás

Ha mindenképpen friss snapshot kell, változtass valamit a paraméteren (pl. &v=2026-05-01) — más hash, új kép.

Csomag-szintű kvóta

A kvóta csak a cache-miss kéréseket számolja — ha a cache-ből jön a válasz, nem rontod a havi keretet. A naptári hónap alapján reset-elődik (UTC).

Node.js példa

import fs from 'node:fs/promises';

const r = await fetch(
  `https://promnet.hu/api/screenshot?url=${encodeURIComponent('https://example.com')}&width=1200&height=630&format=png`,
  { headers: { Authorization: `Bearer ${process.env.PROMNET_TOKEN}` } },
);
if (!r.ok) {
  const err = await r.json();
  throw new Error(err.error);
}
await fs.writeFile('example.png', Buffer.from(await r.arrayBuffer()));
console.log('Cache:', r.headers.get('x-screenshot-cache'));
console.log('Kvóta:', r.headers.get('x-screenshot-quota-used'),
            '/', r.headers.get('x-screenshot-quota-total'));

Python példa

import os, requests

token = os.environ["PROMNET_TOKEN"]
r = requests.get(
    "https://promnet.hu/api/screenshot",
    params={"url": "https://example.com", "width": 1200, "height": 630, "format": "png"},
    headers={"Authorization": f"Bearer {token}"},
)
r.raise_for_status()
with open("example.png", "wb") as f:
    f.write(r.content)
print("Cache:", r.headers.get("x-screenshot-cache"))

Hibakódok

Biztonsági korlátozások

A target-URL-re a következő szabályok érvényesek:

• csak https:// — http:// nem engedélyezett (man-in-the-middle védelem)
• max 2000 karakter — query-paraméter-bombázás ellen
• belső IP-tartományok tiltva — 10.x, 192.168.x, 172.16-31.x, 169.254.x (RFC1918 + linklocal)
• .internal, .local, .localhost TLD-k tiltva — Kubernetes/cluster-belső név-feloldás védelem
• promnet.hu önmaga tiltva — végtelen-ciklus elkerülése

Ha legitim use-case-be ütközöl egy ilyen szabályba (pl. saját staging környezet .local TLD-vel), írj nekünk a [email protected] címre — be tudunk venni allowlist-re az azonosítást követően.

Mit nem tud (még)?

• Auth-olt oldalak screenshot-olása — login mögötti oldalakhoz pillanatnyilag nincs cookie/header-passthrough.
• Mobil-emuláció — viewport megadható, de pl. Touch / mobile UA fix.
• PDF-export — csak PNG/JPEG.
• Egyedi delay — ha az oldal sok JS-t tölt, a networkidle0 event-re várunk fix 15s timeout-tal.

Ezek a roadmap-en vannak. Ha pont a te use-case-edhez hiányzik egy feature, jelezd a [email protected] címen.