Przewodnik integracji API renderowania stron WebExtrator

POST https://api.acedata.cloud/webextrator/render API renderowania stron WebExtrator to usługa renderowania stron oparta na bezgłowym Chromium. Podaj URL, a zwróci w pełni wyrenderowany HTML (w tym treści wstrzyknięte przez JS), czysty tekst, tytuł strony i końcowy URL. Render jest najbardziej podstawowym interfejsem WebExtrator. Jeśli potrzebujesz ustrukturyzowanych wyników ekstrakcji (treść artykułu, cena produktu, składniki przepisu …), użyj /webextrator/extract —— uruchamia on cały potok ekstrakcji typowanej na tej samej podstawie renderowania.

Proces aplikacji

Aby korzystać ze strony usługi WebExtrator, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później.

Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności składania osobnego wniosku dla każdej usługi. Pierwszy wniosek zapewnia darmowy limit, umożliwiający bezpłatne wypróbowanie; gdy limit jest niewystarczający, możesz doładować uniwersalne saldo w konsoli.

📘 Pełna dokumentacja: Strona usługi WebExtrator →

Uwierzytelnianie

Wszystkie interfejsy WebExtrator korzystają ze standardowego uwierzytelniania Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parametry żądania

Pole	Typ	Wymagane	Domyślnie	Opis
`url`	string	✅	—	URL strony do wyrenderowania, musi być `http(s)://`.
`user_agent`	string	❌	Rotacja wbudowanej puli UA	Niestandardowy User-Agent.
`timeout`	integer	❌	`30`	Limit czasu pojedynczej nawigacji (dodatnia liczba całkowita sekund).
`wait_until`	enum	❌	`load`	Zdarzenie zakończenia ładowania: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Dodatkowy czas oczekiwania w sekundach po wyzwoleniu `wait_until` (nieujemna liczba całkowita) (do wtórnego renderowania SPA).
`wait_for_selector`	string	❌	—	Oczekiwanie na pojawienie się tego selektora CSS, stabilniejsze niż `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Blokowane typy zasobów, opcjonalnie: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Dodatkowe nagłówki żądania HTTP (na przykład `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookie wstrzykiwane przed nawigacją, struktura poniżej.
`callback_url`	string	❌	—	Adres zwrotny w trybie asynchronicznym, platforma `POST` pełny wynik na ten adres po zakończeniu zadania.
`bypass_cache`	boolean	❌	`false`	Pomija odczyt z pamięci podręcznej Redis (ale nadal zapisuje bieżący wynik z powrotem do pamięci podręcznej).
`cache_ttl_seconds`	integer	❌	`3600`	Niestandardowy TTL pamięci podręcznej dla bieżącego zapisu, przekazanie `0` oznacza brak buforowania bieżącej odpowiedzi.
`async`	boolean	❌	`false`	Ustawienie `true` natychmiast zwraca `task_id`, wynik jest odbierany przez `callback_url` lub Tasks API.

Kontrakt platformy jednolicie używa snake_case. Wewnętrzna usługa renderowania obsługuje camelCase, ale wywołania zewnętrzne zawsze używają snake_case.

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

Odpowiedź synchroniczna

{
  "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
  }
}

Pole	Typ	Opis
`data.kind`	string	Stałe `"render"`.
`data.url`	string	Przesłany przez Ciebie URL.
`data.finalUrl`	string	Końcowy URL po śledzeniu przekierowań.
`data.title`	string	Wyrenderowany `document.title`.
`data.status`	number \| null	Kod statusu HTTP głównej nawigacji.
`data.html`	string	Pełny HTML po wyrenderowaniu.
`data.text`	string	Migawka `document.body.innerText` (aby uzyskać czystszą treść, użyj Extract).
`data.userAgent`	string	Faktycznie użyty UA.
`data.elapsedMs`	number	Tylko czas renderowania przez przeglądarkę.
`data.cached`	boolean?	`true` przy trafieniu w pamięć podręczną.
`data.cacheStoredAt`	number?	Znacznik czasu Unix w milisekundach pierwszego zapisu wpisu pamięci podręcznej.

Odpowiedź asynchroniczna

Gdy async=true (lub podano callback_url), natychmiast zwracane jest (HTTP 200):

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

Wynik zostanie przesłany przez POST do callback_url (jeśli skonfigurowano) albo aktywnie odpytywany przez /webextrator/tasks.

Struktura callbacku

Platforma wykonuje POST dokładnie takiego samego envelope jak w trybie synchronicznym do callback_url, Content-Type: application/json. Zwrócenie dowolnego 2xx jest uznawane za potwierdzenie; 5xx będzie ponawiane z wykładniczym wycofaniem przez około 5 minut.

Odpowiedź błędu

HTTP	`error.code`	Znaczenie
400	`bad_request`	Treść żądania nie przeszła walidacji Zod (brak `url`, nieprawidłowy typ …).
401	`unauthorized`	Brakujący lub nieprawidłowy `Authorization: Bearer …`.
402	(x402)	Niewystarczające saldo platformy, zwraca envelope wymagań płatności x402.
408	`timeout`	Nawigacja przekroczyła `timeout`.
429	`queue_busy`	Kolejka synchroniczna jest zatłoczona, spróbuj ponownie lub użyj `async=true`.
500	`internal_error`	Nieobsłużony wyjątek po stronie serwera (awaria przeglądarki itp.), Worker automatycznie ponawia próbę raz.

Struktura błędu:

{
  "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" }
}

Przykłady

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);

Asynchronicznie + 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"
  }'

Natychmiast zwraca { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }; po ukończeniu zadania platforma wykona POST z pełnym wynikiem do Twojego callback_url.

Wymuszone pominięcie pamięci podręcznej

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
  }'

Wskazówki i pułapki

Wybór wait_until jest bardzo ważny. networkidle jest najstabilniejsze, ale najwolniejsze; domcontentloaded jest szybkie, ale może pominąć treści wstrzykiwane asynchronicznie; load nadaje się do tradycyjnych stron statycznych.
Klucz pamięci podręcznej ignoruje async. Synchroniczne i asynchroniczne żądania tego samego URL trafiają do tego samego wpisu pamięci podręcznej, swobodne przełączanie nie powoduje unieważnienia.
Klucz pamięci podręcznej ignoruje bypass_cache i cache_ttl_seconds. Te dwa parametry są przełącznikami operacyjnymi, nie wpływają na treść odpowiedzi.
cookies i headers segmentują pamięć podręczną. Dostosowanie tych dwóch parametrów spowoduje, że pierwsze trafienie dla tej samej kombinacji się nie powiedzie.
Rozbudowane SPA często przekraczają domyślne 30 sekund. Zalecane są timeout: 60, wait_until: "domcontentloaded", delay: 4, a następnie użycie wait_for_selector do oczekiwania na elementy, które naprawdę Cię interesują.
block_resources to najszybsza droga do zmniejszenia opóźnienia. Obrazy / czcionki / multimedia są domyślnie blokowane; jeśli Twoje wyodrębnianie nie zależy od układu CSS, dodanie stylesheet może jeszcze je przyspieszyć.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Przewodnik integracji API renderowania stron WebExtrator

Proces aplikacji

Uwierzytelnianie

Parametry żądania

Odpowiedź synchroniczna

Odpowiedź asynchroniczna

Struktura callbacku

Odpowiedź błędu

Przykłady

cURL

Python (requests)

Node.js (fetch)

Asynchronicznie + callback

Wymuszone pominięcie pamięci podręcznej

Wskazówki i pułapki

​Proces aplikacji

​Uwierzytelnianie

​Parametry żądania

​Struktura Cookie

​Odpowiedź synchroniczna

​Odpowiedź asynchroniczna

​Struktura callbacku

​Odpowiedź błędu

​Przykłady

​cURL

​Python (requests)

​Node.js (fetch)

​Asynchronicznie + callback

​Wymuszone pominięcie pamięci podręcznej

​Wskazówki i pułapki

Proces aplikacji

Uwierzytelnianie

Parametry żądania

Struktura Cookie

Odpowiedź synchroniczna

Odpowiedź asynchroniczna

Struktura callbacku

Odpowiedź błędu

Przykłady

cURL

Python (requests)

Node.js (fetch)

Asynchronicznie + callback

Wymuszone pominięcie pamięci podręcznej

Wskazówki i pułapki