WebExtrator Przewodnik po integracji API renderowania stron

POST https://api.acedata.cloud/webextrator/render WebExtrator API renderowania stron to usługa renderowania stron oparta na bezgłowym Chromium. Podaj URL, zwraca całkowicie wyrenderowany HTML (w tym treści wstrzyknięte przez JS), czysty tekst, tytuł strony i ostateczny URL. Render to najniższy poziom interfejsu WebExtrator. Jeśli potrzebujesz ustrukturyzowanych wyników ekstrakcji (treść artykułu, ceny produktów, składniki przepisu …), użyj /webextrator/extract — działa na tej samej podstawie renderowania i uruchamia pełną linię ekstrakcji typów.

Proces aplikacji

Aby korzystać z usługi WebExtrator, najpierw przejdź do konsoli Ace Data Cloud i uzyskaj swój token API, aby go zachować.

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi. Pierwsze zgłoszenie otrzyma darmowy limit, aby móc skorzystać z usługi; gdy limit się wyczerpie, można doładować saldo ogólne w konsoli.

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

Autoryzacja

Wszystkie interfejsy WebExtrator używają standardowej autoryzacji Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parametry żądania

Pole	Typ	Wymagane	Domyślne	Opis
`url`	string	✅	—	URL strony do renderowania, musi być `http(s)://`.
`user_agent`	string	❌	Wbudowana pula UA	Niestandardowy User-Agent.
`timeout`	number	❌	`30`	Czas oczekiwania na pojedynczą nawigację (sekundy).
`wait_until`	enum	❌	`networkidle`	Zdarzenie zakończenia ładowania: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	number	❌	`0`	Dodatkowy czas oczekiwania w sekundach po wyzwoleniu `wait_until` (do ponownego renderowania SPA).
`wait_for_selector`	string	❌	—	Czekaj na pojawienie się tego selektora CSS, bardziej stabilne niż `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Typy zasobów do zablokowania, opcjonalne: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Dodatkowe nagłówki HTTP (np. `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Ciasteczka wstrzykiwane przed nawigacją, struktura poniżej.
`callback_url`	string	❌	—	Adres zwrotny w trybie asynchronicznym, platforma wyśle pełne wyniki na ten adres po zakończeniu zadania.
`bypass_cache`	boolean	❌	`false`	Pomijaj odczyt z pamięci podręcznej Redis (ale nadal zapisze wyniki w pamięci podręcznej).
`cache_ttl_seconds`	number	❌	`3600`	Niestandardowy TTL pamięci podręcznej dla tego zapisu, przekazanie `0` oznacza brak pamięci podręcznej dla tej odpowiedzi.
`async`	boolean	❌	`false`	Ustaw na `true`, aby natychmiast zwrócić `task_id`, wyniki można pobrać przez `callback_url` lub API zadań.

Umowa platformy używa jednolicie snake_case. Wewnętrzne usługi renderowania obsługują camelCase, ale zewnętrzne wywołania zawsze używają snake_case.

Struktura ciasteczek

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

Odpowiedź synchronizacyjna

{
  "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	URL, który przesłałeś.
`data.finalUrl`	string	Ostateczny URL po przekierowaniach.
`data.title`	string	`document.title` po renderowaniu.
`data.status`	number \| null	Kod stanu HTTP głównej nawigacji.
`data.html`	string	Całkowity HTML po renderowaniu.
`data.text`	string	Zrzut `document.body.innerText` (jeśli potrzebujesz czystszej treści, użyj Extract).
`data.userAgent`	string	Rzeczywisty używany UA.
`data.elapsedMs`	number	Czas renderowania w przeglądarce.
`data.cached`	boolean?	`true`, gdy trafiono w pamięć podręczną.
`data.cacheStoredAt`	number?	Znacznik czasu Unix w milisekundach, kiedy wpis pamięci podręcznej został po raz pierwszy zapisany.

Odpowiedź asynchroniczna

async=true (lub podanie callback_url) natychmiast zwraca (HTTP 200):

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

Wyniki zostaną przesłane za pomocą POST do callback_url (jeśli skonfigurowano), lub można je aktywnie sprawdzić przez /webextrator/tasks.

Struktura callbacku

Platforma POST wysyła envelope identyczny jak w trybie synchronizacyjnym do callback_url, Content-Type: application/json. Zwrócenie dowolnego 2xx uznawane jest za potwierdzenie; 5xx będzie ponownie próbowane z wykładniczym opóźnieniem przez około 5 minut.

Odpowiedź błędu

HTTP	`error.code`	Znaczenie
400	`bad_request`	Ciało żądania nie przeszło walidacji Zod (brak `url`, nieprawidłowy typ …).
401	`unauthorized`	Brak lub nieprawidłowy `Authorization: Bearer …`.
402	(x402)	Niewystarczający saldo na platformie, zwróć x402 żądanie płatności envelope.
408	`timeout`	Nawigacja przekroczyła `timeout`.
429	`queue_busy`	Kolejka synchronizacji jest zajęta, spróbuj ponownie lub użyj `async=true`.
500	`internal_error`	Nieprzetworzony wyjątek po stronie serwera (np. awaria przeglądarki), Worker automatycznie spróbuje ponownie.

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: Nieprawidłowy url" }
}

Przykład

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 }; gdy zadanie zostanie zakończone, platforma wyśle pełny wynik na twój callback_url.

Wymuszenie ominięcia 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 najstabilniejszy, ale najwolniejszy; domcontentloaded jest szybki, ale może pominąć asynchronicznie wstrzykiwane treści; load jest odpowiedni dla tradycyjnych stron statycznych.
Klucz pamięci podręcznej ignoruje async. Synchronizacja i asynchroniczne żądania dla tego samego URL trafiają do tego samego wpisu pamięci podręcznej, swobodne przełączanie nie spowoduje błędu.
Klucz pamięci podręcznej ignoruje bypass_cache i cache_ttl_seconds. Te dwa są przełącznikami operacyjnymi, nie wpływają na treść odpowiedzi.
cookies i headers będą miały oddzielne pamięci podręczne. Dostosowanie tych dwóch spowoduje, że pierwsze trafienie dla tego samego zestawu nie powiedzie się.
Przebudowa SPA często przekracza domyślne 30 sekund. Zaleca się timeout: 60, wait_until: "domcontentloaded", delay: 4, a następnie w połączeniu z wait_for_selector, aby poczekać na naprawdę istotne elementy.
block_resources to najszybsza droga do zmniejszenia opóźnienia. Domyślnie zablokowane są obrazy / czcionki / media; jeśli nie zależy ci na układzie CSS, dodanie stylesheet może przyspieszyć jeszcze bardziej.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Coding

WebExtrator Przewodnik po integracji API renderowania stron

Proces aplikacji

Autoryzacja

Parametry żądania

Struktura ciasteczek

Odpowiedź synchronizacyjna

Odpowiedź asynchroniczna

Struktura callbacku

Odpowiedź błędu

Przykład

cURL

Python (requests)

Node.js (fetch)

Asynchronicznie + Callback

Wymuszenie ominięcia pamięci podręcznej

Wskazówki i pułapki

​Proces aplikacji

​Autoryzacja

​Parametry żądania

​Struktura ciasteczek

​Odpowiedź synchronizacyjna

​Odpowiedź asynchroniczna

​Struktura callbacku

​Odpowiedź błędu

​Przykład

​cURL

​Python (requests)

​Node.js (fetch)

​Asynchronicznie + Callback

​Wymuszenie ominięcia pamięci podręcznej

​Wskazówki i pułapki

Proces aplikacji

Autoryzacja

Parametry żądania

Struktura ciasteczek

Odpowiedź synchronizacyjna

Odpowiedź asynchroniczna

Struktura callbacku

Odpowiedź błędu

Przykład

cURL

Python (requests)

Node.js (fetch)

Asynchronicznie + Callback

Wymuszenie ominięcia pamięci podręcznej

Wskazówki i pułapki