API Dokumentation

1. Registrieren Sie sich kostenlos und erstellen Sie in der Konsole unter „API Key“ einen API Key.
2. Übergeben Sie den API Key im Request-Header X-Access-Key und rufen Sie den Screenshot-Endpunkt auf:

curl "https://glanceshot.com/v1/screenshot?url=https://example.com&full_page=true" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -o screenshot.png

Jede Anfrage benötigt einen API Key. Sie können ihn auf eine der folgenden Arten übergeben:

• Request-Header X-Access-Key: gls_… (empfohlen für serverseitige Aufrufe)
• Query-Parameter access_key=gls_… (nur für serverseitige Aufrufe, nicht in Webseiten einbetten)
• Signierte URL (zum Einbetten in Webseiten, ohne API Key oder secret offenzulegen)

Der API Key wird nur bei der Erstellung einmal im Klartext angezeigt. Bewahren Sie ihn sicher auf. Bei einer Offenlegung können Sie ihn in der Konsole deaktivieren.

Screenshot-spezifische Parameter:

Gemeinsame Parameter für Screenshots und PDFs:

Single-Page-Anwendungen aufnehmen (React, Vue usw.):Die Seite führt JavaScript in einem echten Browser aus, bevor der Screenshot erstellt wird. Die Standardstrategie networkidle wartet, bis die Seite ihre Daten geladen hat. Werden Inhalte erst danach per Timer oder Animation gerendert, geben Sie mit wait_for_selector ein Element an, das signalisiert, dass der Inhalt bereit ist. Gibt es kein geeignetes Element, können Sie mit delay zusätzliche Wartezeit einplanen.

Jedes PDF verbraucht 2 Kontingenteinheiten. Vor dem Drucken wird die Seite einmal durchgescrollt, um Lazy-Loading-Inhalte zu laden. Zusätzlich zu den gemeinsamen Parametern werden unterstützt:

curl -X POST "https://glanceshot.com/v1/pdf" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Quartalsbericht</h1><p>Inhalt …</p>", "paper": "a4"}' \
  -o report.pdf

Standardmäßig (response_type=binary) wird die Datei direkt zurückgegeben, mit dem passenden Format in Content-Type. Response-Header:

• X-Request-Id: ID dieser Anfrage; bitte bei der Fehleranalyse angeben
• X-Glanceshot-Cache: HIT oder MISS
• X-Glanceshot-Truncated: true: Die vollständige Seite wurde bei 20,000 Pixeln Höhe abgeschnitten
• X-Glanceshot-Format-Changed: webp: PNG über 5 MB wurde automatisch in WebP umgewandelt (keine Umwandlung bei expliziter Angabe von format=png)

Mit response_type=json werden die Datei-URL und Metadaten zurückgegeben:

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response_type": "json"}'

# Rückgabe
{
  "url": "https://glanceshot.com/i/3f/3f9c….png",
  "cache_hit": false,
  "duration_ms": 1284,
  "format": "png",
  "width": 1280,
  "height": 800,
  "request_id": "req_01j…"
}

Sie möchten eine Screenshot-URL direkt in <img src> einbetten, ohne Ihren API Key offenzulegen? Eine signierte URL enthält keinen API Key, sondern nur die öffentliche key_id. Die Signatur berechnen Sie auf Ihrem eigenen Server mit dem zugehörigen secret. Key ID und secret finden Sie in der Konsole auf der Seite „API Key“:

canonical = Alle Parameter außer signature lexikografisch nach Parameternamen sortieren,
            jeden Eintrag als k=urlencode(v) kodieren (RFC 3986, Leerzeichen als %20) und mit & verbinden
signature = hex(HMAC-SHA256(secret, canonical))

Eine gültige Signatur authentifiziert die Anfrage. Anfragen mit fehlender oder ungültiger Signatur werden abgelehnt. Jede Parameteränderung (etwa an url) macht die Signatur ungültig. Der optionale Parameter expires (Unix-Zeit in Sekunden) wird in die Signatur einbezogen; nach Ablauf wird signature_expired zurückgegeben. Um den Cache zu aktualisieren, ändern Sie einen bedeutungslosen Parameter (z. B. v=2) und signieren die URL erneut. Signierte URLs unterstützen nur GET-Aufrufe der Screenshot- und PDF-Endpunkte und dürfen keine Proxy-Parameter enthalten.

key_id ist öffentlich und reicht allein nicht für API-Aufrufe aus. Fügen Sie den API Key (access_key) nicht in signierte URLs ein, sonst wird direkt invalid_params zurückgegeben. Falls Sie Ihren API Key bereits in eine Webseite eingebettet haben, deaktivieren Sie ihn in der Konsole und erstellen Sie einen neuen.

import crypto from "node:crypto";

// RFC-3986-Kodierung (Leerzeichen als %20), muss den serverseitigen Regeln entsprechen
const enc = (v) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());

function signedUrl(params, keyId, secret) {
  const all = { ...params, key_id: keyId };
  const canonical = Object.keys(all).sort().map((k) => `${k}=${enc(String(all[k]))}`).join("&");
  const signature = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return `https://glanceshot.com/v1/screenshot?${canonical}&signature=${signature}`;
}

const src = signedUrl({ url: "https://example.com", viewport_width: 1200 }, KEY_ID, SECRET);
// <img src={src} alt="Webseitenvorschau" />

Wenn Sie eine Webseite aus einem bestimmten Land oder einer bestimmten Region aufrufen möchten (z. B. um die lokale Sprache, Inhalte und Preise zu sehen), können Sie einen selbst gebuchten Proxy in der Anfrage angeben. Die Proxy-Kosten tragen Sie selbst. Die Seite sowie alle Bilder, Skripte und API-Anfragen der Seite werden über diesen Proxy geladen. Unterstützt werden socks5:// und http://, auch mit Benutzername und Passwort.

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "proxy": "socks5://user:pass@203.0.113.10:1080"}' \
  -o screenshot.png

• proxy darf nur im Body einer POST-Anfrage stehen. GET-Anfragen, signierte URLs und Batch-Aufträge unterstützen diesen Parameter nicht, damit die Proxy-Zugangsdaten nicht in URLs, im Browserverlauf oder auf Webseiten erscheinen.
• Enthalten Benutzername oder Passwort Sonderzeichen wie @ oder :, müssen diese zuerst URL-codiert werden (z. B. @ als %40).
• Anfragen mit Proxy werden separat zwischengespeichert. Die Ergebnisse werden weder für Anfragen ohne Proxy noch für Anfragen mit anderen Proxys wiederverwendet.
• Ist der Proxy nicht erreichbar, schlägt die Authentifizierung fehl oder lässt sich die Zielwebsite nicht aufrufen, wird proxy_failed zurückgegeben. Die Anfrage wird nicht berechnet. message enthält die genaue Ursache.
• Der Proxy muss eine öffentlich erreichbare Adresse haben. Für die Ziel-URL gelten dieselben Einschränkungen wie ohne Proxy: Interne Netzwerkadressen sind nicht zulässig.
• Beachten Sie beim Zugriff auf Websites über einen Proxy die Nutzungsbedingungen der Zielwebsite und die örtlichen Gesetze.

Um Seiten zu erfassen, die nur nach einer Anmeldung sichtbar sind, können Sie den Anmeldestatus Ihres eigenen Kontos übergeben. Dafür gibt es zwei Möglichkeiten: Übergeben Sie cookies, headers, local_storage und session_storage direkt in der Anfrage, oder speichern Sie den Anmeldestatus mit der Glanceshot-Browser-Erweiterung als „Anmeldeprofil“ und übergeben Sie in der Anfrage nur login_profile.

curl -X POST "https://glanceshot.com/v1/screenshot"   -H "X-Access-Key: $GLANCESHOT_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": "sid=YOUR_SESSION; theme=dark",
    "local_storage": {"token": "YOUR_TOKEN"}
  }' -o screenshot.png

• Die Erweiterung kann Zugangsdaten auslesen, auf die Seitenskripte keinen Zugriff haben (einschließlich HttpOnly-Cookies), sowie localStorage und IndexedDB. Sie eignet sich für die meisten Websites. Installieren und verbinden Sie die Erweiterung auf der Seite „Anmeldeprofile“ in der Konsole.
• Der Anmeldestatus kann nur im Body einer POST-Anfrage übergeben werden (GET und signierte URLs werden abgelehnt). Er wird weder in Logs noch im Aufrufverlauf gespeichert. Anfragen mit Anmeldestatus werden nach diesem Status getrennt zwischengespeichert; der Cache wird nicht mit anderen Nutzern geteilt.
• Wenn ein Anmeldestatus übergeben wurde, die Seite jedoch zur Anmeldeseite zurückleitet, wird login_expired zurückgegeben und die Anfrage nicht berechnet. Der Anmeldestatus ist dann abgelaufen; synchronisieren Sie ihn erneut mit der Erweiterung.
• Bei Websites, deren Sitzung an ein Gerät oder eine IP gebunden ist und deren Anmeldung sich daher nicht in der Cloud wiederherstellen lässt (z. B. Onlinebanking), können Sie mit „Aktuelle Seite erfassen“ in der Erweiterung einen Screenshot in Ihrem eigenen Browser erstellen und anschließend hochladen.

Anfragen mit identischen Parametern werden aus dem Cache bedient. Weggelassene Parameter gelten als identisch mit explizit angegebenen Standardwerten; Authentifizierungs- und Cache-Parameter werden nicht verglichen. Bei einem Cache-Treffer liefert der Binärmodus eine 302-Weiterleitung zur Datei-URL mit Cache-Control. Der Browser folgt der Weiterleitung automatisch und speichert die Datei im Cache. Im JSON-Modus wird cache_hit: true zurückgegeben.

Cache-Treffer werden nicht berechnet.Gleichzeitige Anfragen mit identischen Parametern lösen nur einen Rendervorgang aus.

• Nur erfolgreiche Anfragen (2xx) ohne Cache-Treffer werden berechnet: 1 Kontingenteinheit pro Screenshot, 2 pro PDF.
• Bei Zeitüberschreitungen, Rendering-Fehlern, Fehlern oder Zugriffssperren der Zielwebsite, ungültigen Parametern und fehlgeschlagener Authentifizierung wird kein Kontingent abgezogen.
• Das Kontingent wird zu Beginn jedes Kalendermonats (UTC) zurückgesetzt. Der kostenlose Tarif enthält 100 Kontingenteinheiten pro Monat. Nach Verbrauch wird quota_exceeded zurückgegeben.
• Bei Überschreitung der Anfragen pro Sekunde oder der gleichzeitigen Anfragen wird 429 zurückgegeben. Der Response-Header Retry-After enthält die empfohlene Wartezeit in Sekunden.
• Maximale Renderdauer: 30 Sekunden; maximales Downloadvolumen pro Seite: 50 MB; maximale Ausgabedateigröße: 50 MB.

Die genauen Limits der einzelnen Tarife finden Sie unter Preise.

Fehlerantworten werden immer als JSON zurückgegeben:

{
  "error": {
    "code": "render_failed",
    "message": "target responded with an error status",
    "upstream_status": 404,
    "request_id": "req_01j…"
  }
}

Übermitteln Sie 1–100 URLs auf einmal. Der Endpunkt gibt sofort eine Auftrags-ID zurück (HTTP 202); die Screenshots werden im Hintergrund nacheinander erstellt. Ideal für mehrere Screenshots, ohne die Verbindung offen halten zu müssen. Sie können den Status regelmäßig abfragen oder webhook_url angeben, um nach Abschluss aller Aufgaben benachrichtigt zu werden. Die Authentifizierung entspricht der synchronen API (nur per Request-Header oder Parameter access_key, keine signierten URLs).

curl -X POST "https://glanceshot.com/v1/batch" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "urls": ["https://example.com", "https://example.org"],
    "options": { "full_page": true, "format": "webp" },
    "webhook_url": "https://your-app.com/hooks/glanceshot"
  }'

# Rückgabe: 202
{
  "id": "bat_01j…",
  "type": "screenshot",
  "status": "queued",
  "total": 2, "succeeded": 0, "failed": 0,
  "created_at": "2026-10-18T09:30:00Z", "completed_at": null,
  "webhook": { "url": "https://your-app.com/hooks/glanceshot", "status": "none", "attempts": 0 },
  "items": [
    { "index": 0, "url": "https://example.com", "status": "pending", "result": null, "error": null },
    { "index": 1, "url": "https://example.org", "status": "pending", "result": null, "error": null }
  ]
}

Fortschritt abfragen: Der Auftragsstatus status durchläuft queued (in der Warteschlange), running (in Bearbeitung) und completed (alles abgeschlossen, unabhängig von Erfolg oder Fehler). Jede URL hat den Status pending, running, succeeded oder failed. Bei Erfolg enthält result die Datei-URL, bei einem Fehler enthält error den Fehlercode (identisch mit den synchronen Endpunkten).

curl "https://glanceshot.com/v1/batch/bat_01j…" -H "X-Access-Key: $GLANCESHOT_KEY"

{
  "id": "bat_01j…",
  "status": "completed",
  "total": 2, "succeeded": 1, "failed": 1,
  "completed_at": "2026-10-18T09:30:12Z",
  "items": [
    {
      "index": 0, "url": "https://example.com", "status": "succeeded", "duration_ms": 1830,
      "result": { "url": "https://glanceshot.com/i/3f/3f9c….webp", "mime": "image/webp", "width": 1280, "height": 2410, "cache_hit": false },
      "error": null
    },
    {
      "index": 1, "url": "https://example.org", "status": "failed", "duration_ms": 640,
      "result": null,
      "error": { "code": "render_failed", "message": "target responded with an error status" }
    }
  ]
}

• Es gelten dieselben Abrechnungsregeln wie bei den synchronen Endpunkten: pro erfolgreich verarbeiteter URL 1 Kontingenteinheit für einen Screenshot oder 2 für ein PDF. Cache-Treffer und Fehler verbrauchen kein Kontingent.
• Ist das Kontingent beim Einreichen bereits aufgebraucht, wird sofort quota_exceeded zurückgegeben. Wird es während der Verarbeitung aufgebraucht, schlagen die verbleibenden URLs mit quota_exceeded fehl.
• Pro Konto sind höchstens 5 noch nicht abgeschlossene Stapelaufträge gleichzeitig erlaubt. Bei Überschreitung wird too_many_batches zurückgegeben.
• Die Gültigkeitsdauer der Ergebnisdateien wird durch options.cache_ttl bestimmt (standardmäßig 1 Tag). Laden Sie die Dateien rechtzeitig herunter und speichern Sie sie.
• In Abfrageergebnissen und Webhooks wird webhook.url nur bis zum Pfad angezeigt, ohne Query-String.

Wenn Sie webhook_url angeben, senden wir nach Abschluss des gesamten Auftrags eine POST-Anfrage an diese URL. Der Request-Body ist JSON: { "event": "batch.completed", "batch": { … } }. Dabei entspricht batch genau der Antwort des Abfrage-Endpunkts. Request-Header:

• X-Glanceshot-Signature: t=1760779812,v1=5d3f…: t ist der Sendezeitpunkt (Unix-Zeit in Sekunden), v1 die Signatur
• X-Glanceshot-Event: batch.completed, X-Glanceshot-Delivery-Attempt: 1 (Nummer des Zustellversuchs)

v1 = hex(HMAC-SHA256(secret, t + "." + Unveränderter Request-Body))
secret ist das Signatur-Secret des API Key, mit dem der Auftrag eingereicht wurde (in der Konsole auf der Seite „API Key“ einsehbar).

• Antworten Sie innerhalb von 10 Sekunden mit 2xx, andernfalls gilt die Zustellung als fehlgeschlagen. Bei einem Fehler wird die Zustellung nach 10 Sekunden, 1 Minute und 5 Minuten jeweils einmal wiederholt (insgesamt maximal 4 Versuche).
• In seltenen Fällen können Sie für denselben Auftrag mehrere Benachrichtigungen erhalten. Erkennen Sie Duplikate anhand von batch.id.
• Berechnen Sie die Signatur anhand der empfangenen, unveränderten Bytes. Prüfen Sie außerdem, dass t höchstens wenige Minuten von der aktuellen Zeit abweicht, um Replay-Angriffe zu verhindern.
• Die Callback-URL muss eine öffentlich erreichbare http(s)-Adresse sein und darf nicht auf ein internes Netzwerk verweisen.

import crypto from "node:crypto";

// rawBody muss die empfangenen Originalbytes enthalten. Nicht zuerst mit JSON.parse parsen und anschließend erneut serialisieren.
function verifyGlanceshotWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // Schutz vor Replay-Angriffen
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), got);
}

// verifyGlanceshotWebhook(req.rawBody, req.headers["x-glanceshot-signature"], GLANCESHOT_SECRET)

Keine Authentifizierung erforderlich. Gibt den Knotenstatus und den Status des Browser-Pools zurück (gesamt, belegt, frei).