WebExtrator Web-Rendering-API-Integrationsleitfaden

POST https://api.acedata.cloud/webextrator/render Die WebExtrator Web-Rendering-API ist ein auf headlosem Chromium basierender Web-Rendering-Dienst. Geben Sie eine URL an, und erhalten Sie das vollständig gerenderte HTML zurück (einschließlich von JS eingefügter Inhalte), reinen Text, den Seitentitel und die endgültige URL. Render ist die unterste Schnittstelle von WebExtrator. Wenn Sie strukturierte Extraktionsergebnisse benötigen (Artikelinhalt, Produktpreise, Rezeptzutaten …), verwenden Sie bitte /webextrator/extract —— darauf läuft auf derselben Rendering-Grundlage eine vollständige typisierte Extraktionspipeline.

Antragsprozess

Um die WebExtrator-Dienstseite zu verwenden, rufen Sie zuerst die Ace Data Cloud-Konsole auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn als Reserve auf.

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden; nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass Sie ihn für jeden Dienst separat beantragen müssen. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, das kostenlos ausprobiert werden kann; wenn das Kontingent nicht ausreicht, können Sie in der Konsole ein allgemeines Guthaben aufladen.

📘 Vollständige Dokumentation: WebExtrator-Dienstseite →

Authentifizierung

Alle WebExtrator-Schnittstellen verwenden die Standard-Bearer-Token-Authentifizierung:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Anfrageparameter

Feld	Typ	Erforderlich	Standard	Beschreibung
`url`	string	✅	—	Die zu rendernde Seiten-URL muss `http(s)://` sein.
`user_agent`	string	❌	Rotation des integrierten UA-Pools	Benutzerdefinierter User-Agent.
`timeout`	integer	❌	`30`	Navigations-Timeout pro Aufruf (positive ganze Sekunden).
`wait_until`	enum	❌	`load`	Ladeabschlussereignis: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Zusätzliche Wartezeit in Sekunden nach Auslösung von `wait_until` (nichtnegative ganze Zahl) (für das sekundäre Rendering von SPAs).
`wait_for_selector`	string	❌	—	Wartet auf das Erscheinen dieses CSS-Selektors, stabiler als `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Blockierte Ressourcentypen, optional: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Zusätzliche HTTP-Anfrage-Header (zum Beispiel `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Vor der Navigation eingefügte Cookies, Struktur siehe unten.
`callback_url`	string	❌	—	Callback-Adresse im asynchronen Modus; die Plattform sendet bei Abschluss der Aufgabe das vollständige Ergebnis per `POST` an diese Adresse.
`bypass_cache`	boolean	❌	`false`	Überspringt das Lesen des Redis-Caches (schreibt dieses Ergebnis jedoch weiterhin zurück in den Cache).
`cache_ttl_seconds`	integer	❌	`3600`	Benutzerdefinierte Cache-TTL für diesen Schreibvorgang; die Übergabe von `0` bedeutet, diese Antwort nicht zu cachen.
`async`	boolean	❌	`false`	Auf `true` setzen, um sofort `task_id` zurückzugeben; das Ergebnis wird über `callback_url` oder die Tasks-API abgerufen.

Der Plattformvertrag verwendet einheitlich snake_case. Der interne Rendering-Dienst unterstützt camelCase, aber für externe Aufrufe wird durchgehend snake_case verwendet.

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

Synchrone Antwort

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

Feld	Typ	Beschreibung
`data.kind`	string	Fest `"render"`.
`data.url`	string	Die von Ihnen übermittelte URL.
`data.finalUrl`	string	Die endgültige URL nach dem Folgen von Weiterleitungen.
`data.title`	string	Das gerenderte `document.title`.
`data.status`	number \| null	Der HTTP-Statuscode der Hauptnavigation.
`data.html`	string	Vollständiges gerendertes HTML.
`data.text`	string	`document.body.innerText`-Snapshot (verwenden Sie Extract für einen saubereren Haupttext).
`data.userAgent`	string	Der tatsächlich verwendete UA.
`data.elapsedMs`	number	Nur Browser-Rendering-Dauer.
`data.cached`	boolean?	Bei einem Cache-Treffer `true`.
`data.cacheStoredAt`	number?	Unix-Millisekundenzeitstempel, zu dem der Cache-Eintrag erstmals geschrieben wurde.

Asynchrone Antwort

Bei async=true (oder wenn callback_url bereitgestellt wird) wird sofort zurückgegeben (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

Das Ergebnis wird per POST an callback_url gesendet (falls konfiguriert), oder aktiv über /webextrator/tasks abgefragt.

Callback-Struktur

Die Plattform sendet per POST denselben Envelope wie im synchronen Modus an callback_url, Content-Type: application/json. Die Rückgabe eines beliebigen 2xx gilt als Bestätigung; bei 5xx wird mit exponentiellem Backoff etwa 5 Minuten lang erneut versucht.

Fehlerantwort

HTTP	`error.code`	Bedeutung
400	`bad_request`	Der Anfragekörper hat die Zod-Validierung nicht bestanden (fehlende `url`, falscher Typ …).
401	`unauthorized`	Fehlende oder ungültige `Authorization: Bearer …`.
402	(x402)	Unzureichendes Plattformguthaben, gibt den x402-Zahlungsanforderungs-Envelope zurück.
408	`timeout`	Die Navigation überschreitet `timeout`.
429	`queue_busy`	Die synchrone Warteschlange ist überlastet, bitte erneut versuchen oder `async=true` verwenden.
500	`internal_error`	Nicht behandelte serverseitige Ausnahme (Browserabsturz usw.), der Worker versucht es automatisch einmal erneut.

Fehlerstruktur:

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid url" }
}

Beispiele

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

Asynchron + Callback

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

Gibt sofort { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 } zurück; wenn die Aufgabe abgeschlossen ist, sendet die Plattform das vollständige Ergebnis per POST an deine callback_url.

Cache-Umgehung erzwingen

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

Hinweise und Fallstricke

Die richtige Wahl von wait_until ist wichtig. networkidle ist am stabilsten, aber am langsamsten; domcontentloaded ist schnell, könnte aber asynchron eingefügte Inhalte verpassen; load eignet sich für traditionelle statische Seiten.
Der Cache-Key ignoriert async. Synchrone und asynchrone Anfragen für dieselbe URL treffen denselben Cache-Eintrag, ein beliebiger Wechsel macht ihn nicht ungültig.
Der Cache-Key ignoriert bypass_cache und cache_ttl_seconds. Diese beiden sind Operationsschalter, die den Antwortinhalt nicht beeinflussen.
cookies und headers segmentieren den Cache. Das Anpassen dieser beiden führt dazu, dass der erste Treffer derselben Kombination fehlschlägt.
Schwere SPAs überschreiten häufig die standardmäßigen 30 Sekunden. Empfohlen werden timeout: 60, wait_until: "domcontentloaded", delay: 4 sowie wait_for_selector, um auf die tatsächlich relevanten Elemente zu warten.
block_resources ist der schnellste Weg zur Verringerung der Latenz. Bilder / Schriftarten / Medien sind standardmäßig bereits blockiert; wenn deine Extraktion nicht von CSS-Layouts abhängt, wird es mit stylesheet noch schneller.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

WebExtrator Web-Rendering-API-Integrationsleitfaden

Antragsprozess

Authentifizierung

Anfrageparameter

Synchrone Antwort

Asynchrone Antwort

Callback-Struktur

Fehlerantwort

Beispiele

cURL

Python (requests)

Node.js (fetch)

Asynchron + Callback

Cache-Umgehung erzwingen

Hinweise und Fallstricke

​Antragsprozess

​Authentifizierung

​Anfrageparameter

​Cookie-Struktur

​Synchrone Antwort

​Asynchrone Antwort

​Callback-Struktur

​Fehlerantwort

​Beispiele

​cURL

​Python (requests)

​Node.js (fetch)

​Asynchron + Callback

​Cache-Umgehung erzwingen

​Hinweise und Fallstricke

Antragsprozess

Authentifizierung

Anfrageparameter

Cookie-Struktur

Synchrone Antwort

Asynchrone Antwort

Callback-Struktur

Fehlerantwort

Beispiele

cURL

Python (requests)

Node.js (fetch)

Asynchron + Callback

Cache-Umgehung erzwingen

Hinweise und Fallstricke