Screenshot API v1

Parameter, Einschränkungen und Beispiele für POST /api/v1/screenshots.

Authentifizierung

Senden Sie Ihren API-Schlüssel im Authorization -Header:

Authorization: Bearer <api_key>

Screenshot erstellen

Endpunkt: POST /api/v1/screenshots

Body: JSON

Minimale Anfrage

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Sync-Anfrage (wenn erlaubt)

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

Wenn das Sync-Zeitfenster vor Abschluss abläuft, gibt die API status=processing. zurück. Pollen Sie weiter mit GET /api/v1/screenshots/{jobId}.

Wichtige Parameter

url

Erforderlich. Ziel-URL, die erfasst werden soll.

mode

Optional. async (Standard) oder sync.

timeoutMs

Erforderlich für sync. Muss > 0 und < 10000.

fullPage

Optional. Für sync -Modus muss es false.

Sync-Modus-Einschränkungen

Selbst wenn Sie mode=sync, anfordern, fällt der Server auf async zurück, sofern nicht gilt:

mode == "sync"

timeoutMs != null

0 < timeoutMs < 10000

fullPage == false

Parameterreferenz (vollständig)

Feld	Typ	Erforderlich	Standard	Hinweise
url	string	Ja	-	Ziel-URL.
mode	string	Nein	async	Akzeptiert async oder sync (Groß-/Kleinschreibung wird ignoriert).;
timeoutMs	int?	Nein	-	Wird nur für Sync verwendet. Muss 0 < timeoutMs < 10000.
fullPage	bool	Nein	false	Sync erfordert false.
viewport	object?	Nein	-	Überschreibt den Viewport.
format	string?	Nein	-	Derzeit wird nur png unterstützt. Andere Formate sind für zukünftige Versionen reserviert.
quality	int?	Nein	-	Derzeit ignoriert (künftig nur für jpeg/webp verwendet).
waitUntil	string?	Nein	-	Empfohlen: load, domcontentloaded, networkidle.
delayMs	int?	Nein	-	Zusätzliche Verzögerung nach waitUntil.
selector	string?	Nein	-	Erfasst nur ein bestimmtes Element.
headers	object?	Nein	-	Wörterbuch zusätzlicher Request-Header.
cookies	array?	Nein	-	Liste der zu injizierenden Cookies.
javascript	string?	Nein	-	Benutzerdefiniertes JS zum Injizieren (implementierungsabhängig).;
css	string?	Nein	-	Benutzerdefiniertes CSS zum Injizieren (implementierungsabhängig).;
device	string?	Nein	-	Empfohlen: desktop/iphone/ipad/pixel.
strictDevice	bool?	Nein	-	Wenn true, sollte ein nicht unterstütztes Gerät fehlschlagen (implementierungsabhängig).;
colorScheme	string?	Nein	-	Empfohlen: light/dark/no-preference.
proxy	string?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.
trace	bool?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.
har	bool?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.
returnDom	bool?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.
returnNetwork	bool?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.
priority	int?	Nein	-	Für zukünftige Versionen reserviert. Derzeit ignoriert.

viewport

Feld	Typ	Erforderlich	Hinweise
viewport.width	int	Nein	Viewport-Breite.
viewport.height	int	Nein	Viewport-Höhe.

cookies[]

Feld	Typ	Erforderlich	Hinweise
cookies[].name	string	Ja	Cookie-Name.
cookies[].value	string	Ja	Cookie-Wert.
cookies[].domain	string?	Nein	Cookie-Domain.
cookies[].path	string?	Nein	Cookie-Pfad.

Antworten

Async (Standard)

{ "jobId": "<guid>", "status": "pending" }

Sync (abgeschlossen)

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

Sync (fehlgeschlagen)

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

Sync (Zeitüberschreitung)

{ "jobId": "<guid>", "status": "processing" }

Für Async-Aufrufe (oder Sync-Timeouts) verwenden Sie GET /api/v1/screenshots/{jobId} zur Statusprüfung. Mögliche Werte: pending, processing, completed, failed, expired.

Fehler

HTTP	Wann	Body
400	Body fehlt oder url fehlt/ist leer	BadRequest
401	Ungültiger/fehlender API-Schlüssel	Middleware-Antwort
402	Kontingent überschritten	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	Rate-Limit erreicht	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	Job nicht gefunden	NotFound

Anwendungsbeispiele

Praktische Beispiele für häufige Integrationsanforderungen.

Auth-Token der Zielseite übergeben (via headers)

Wenn die zu erfassende Seite geschützt ist (Bearer/JWT/Session-Token), leiten Sie es weiter über headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

Cookies setzen (sitzungsbasierter Login)

Wenn die Website Cookies zur Authentifizierung verwendet, übergeben Sie diese mit cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

Benutzerdefinierte Request-Header (User-Agent / Locale)

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

Viewport + Format + Qualität

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

Auf Seitenaufbau warten + Verzögerung hinzufügen

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

Ein bestimmtes Element erfassen (Selector)

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Status abrufen

Job pollen:

GET /api/v1/screenshots/{jobId}