WebExtrator API інтеграційний посібник для рендерингу веб-сторінок

POST https://api.acedata.cloud/webextrator/render WebExtrator API для рендерингу веб-сторінок — це сервіс рендерингу веб-сторінок на основі безголового Chromium. Надсилаючи URL, ви отримуєте повністю відрендерений HTML (включаючи вміст, інжектований через JS), чистий текст, заголовок сторінки та остаточний URL. Render є найнижчим рівнем інтерфейсу WebExtrator. Якщо вам потрібні структуровані результати витягування (основний текст статті, ціни на товари, інгредієнти рецептів тощо), будь ласка, використовуйте /webextrator/extract — він працює на тій же основі рендерингу, але виконує повний набір типізованих витягувальних процесів.

Процес подачі заявки

Щоб використовувати сервіс WebExtrator, спочатку перейдіть до консолі Ace Data Cloud та отримайте свій API Token для резервного копіювання.

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після завершення ви будете автоматично повернені на поточну сторінку. Один API Token дозволяє викликати всі сервіси платформи, не потрібно окремо подавати заявку на кожен сервіс. Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в консолі.

📘 Повна документація: Сервіс WebExtrator →

Аутентифікація

Всі інтерфейси WebExtrator використовують стандартну аутентифікацію Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Параметри запиту

Поле	Тип	Обов’язкове	За замовчуванням	Опис
`url`	string	✅	—	URL сторінки для рендерингу, повинен бути `http(s)://`.
`user_agent`	string	❌	Вбудований пул UA	Користувацький User-Agent.
`timeout`	number	❌	`30`	Час очікування для одного навігаційного запиту (секунди).
`wait_until`	enum	❌	`networkidle`	Подія завершення завантаження: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	number	❌	`0`	Додаткова кількість секунд очікування після спрацьовування `wait_until` (для повторного рендерингу SPA).
`wait_for_selector`	string	❌	—	Очікування появи цього CSS селектора, більш стабільно, ніж `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Типи ресурсів, які потрібно заблокувати, необов’язково: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Додаткові HTTP заголовки запиту (наприклад, `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookie, які потрібно ввести перед навігацією, структура наведена нижче.
`callback_url`	string	❌	—	Адреса зворотного виклику в асинхронному режимі, платформа надішле повний результат на цю адресу, коли завдання буде завершено.
`bypass_cache`	boolean	❌	`false`	Пропустити читання кешу Redis (але все ще запише результати цього разу в кеш).
`cache_ttl_seconds`	number	❌	`3600`	Налаштування TTL кешу для цього запису, передайте `0`, щоб не кешувати цю відповідь.
`async`	boolean	❌	`false`	Встановіть `true`, щоб негайно повернути `task_id`, результати можна отримати через `callback_url` або API Tasks.

Платформені контракти використовують snake_case. Внутрішні сервіси рендерингу підтримують camelCase, але зовнішні виклики завжди використовують snake_case.

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

Синхронна відповідь

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

Поле	Тип	Опис
`data.kind`	string	Фіксоване `"render"`.
`data.url`	string	URL, який ви подали.
`data.finalUrl`	string	Остаточний URL після перенаправлення.
`data.title`	string	`document.title` після рендерингу.
`data.status`	number \| null	HTTP статус код основної навігації.
`data.html`	string	Повний HTML після рендерингу.
`data.text`	string	Сnapshot `document.body.innerText` (для чистішого тексту використовуйте Extract).
`data.userAgent`	string	Фактично використаний UA.
`data.elapsedMs`	number	Час, витрачений лише на рендеринг браузера.
`data.cached`	boolean?	Якщо кеш було використано, то `true`.
`data.cacheStoredAt`	number?	Unix мілісекундний таймштамп, коли кешовий запис було вперше записано.

Асинхронна відповідь

async=true (або надано callback_url) негайно повертає (HTTP 200):

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

Результати будуть надіслані через POST на callback_url (якщо він налаштований), або через /webextrator/tasks активним запитом.

Структура зворотного виклику

Платформа POST надсилає повністю таку ж оболонку, як і в синхронному режимі, на callback_url, Content-Type: application/json. Повернення будь-якого 2xx вважається підтвердженим; 5xx буде повторюватися з експоненційною затримкою протягом приблизно 5 хвилин.

Відповідь про помилку

HTTP	`error.code`	Значення
400	`bad_request`	Тіло запиту не пройшло перевірку Zod (не вистачає `url`, неправильний тип …).
401	`unauthorized`	Відсутній або недійсний `Authorization: Bearer …`.
402	(x402)	Недостатньо коштів на платформі, повертається x402 вимога на оплату.
408	`timeout`	Навігація перевищила `timeout`.
429	`queue_busy`	Черга синхронізації переповнена, будь ласка, спробуйте ще раз або використовуйте `async=true`.
500	`internal_error`	Внутрішня помилка сервера (вимкнення браузера тощо), Worker автоматично повторює спробу.

Структура помилки:

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Неправильний url" }
}

Приклад

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

Асинхронно + зворотний виклик

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

Негайно повертає { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }; коли завдання завершиться, платформа надішле повний результат на ваш callback_url.

Примусове обходження кешу

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

Поради та підводні камені

Важливо правильно вибрати wait_until. networkidle найстабільніший, але найповільніший; domcontentloaded швидкий, але може пропустити асинхронно завантажений контент; load підходить для традиційних статичних сторінок.
Кеш-ключ ігнорує async. Синхронні та асинхронні запити до одного й того ж URL потрапляють в один і той же кеш-елемент, випадкове перемикання не призведе до збою.
Кеш-ключ ігнорує bypass_cache та cache_ttl_seconds. Ці два є перемикачами, не впливають на вміст відповіді.
cookies та headers кешуються окремо. Налаштування цих двох призведе до невдачі при першому попаданні однакових комбінацій.
Важкі SPA часто перевищують стандартні 30 секунд. Рекомендується timeout: 60, wait_until: "domcontentloaded", delay: 4, а також використовувати wait_for_selector для очікування дійсно важливих елементів.
block_resources є найшвидшим шляхом для зменшення затримки. За замовчуванням вже заблоковані зображення / шрифти / медіа; якщо ви витягуєте, не покладаючись на CSS-розмітку, додавання stylesheet може ще більше прискорити процес.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

WebExtrator API інтеграційний посібник для рендерингу веб-сторінок

Процес подачі заявки

Аутентифікація

Параметри запиту

Синхронна відповідь

Асинхронна відповідь

Структура зворотного виклику

Відповідь про помилку

Приклад

cURL

Python (requests)

Node.js (fetch)

Асинхронно + зворотний виклик

Примусове обходження кешу

Поради та підводні камені

​Процес подачі заявки

​Аутентифікація

​Параметри запиту

​Структура Cookie

​Синхронна відповідь

​Асинхронна відповідь

​Структура зворотного виклику

​Відповідь про помилку

​Приклад

​cURL

​Python (requests)

​Node.js (fetch)

​Асинхронно + зворотний виклик

​Примусове обходження кешу

​Поради та підводні камені

Процес подачі заявки

Аутентифікація

Параметри запиту

Структура Cookie

Синхронна відповідь

Асинхронна відповідь

Структура зворотного виклику

Відповідь про помилку

Приклад

cURL

Python (requests)

Node.js (fetch)

Асинхронно + зворотний виклик

Примусове обходження кешу

Поради та підводні камені