Посібник з інтеграції API рендерингу вебсторінок WebExtrator

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

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

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

Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку. Один 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`	integer	❌	`30`	Тайм-аут однієї навігації (додатна ціла кількість секунд).
`wait_until`	enum	❌	`load`	Подія завершення завантаження: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`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	❌	—	Адреса зворотного виклику в асинхронному режимі; платформа надсилає `POST` повного результату на цю адресу після завершення завдання.
`bypass_cache`	boolean	❌	`false`	Пропустити читання кешу Redis (але результат цього разу все одно буде записано назад у кеш).
`cache_ttl_seconds`	integer	❌	`3600`	Власний TTL кешу для цього запису; передайте `0`, щоб не кешувати цю відповідь.
`async`	boolean	❌	`false`	Встановіть `true`, щоб негайно повернути `task_id`; результат отримується через `callback_url` або Tasks API.

Контракт платформи уніфіковано використовує 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	Знімок `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 envelope, повністю ідентичний синхронному режиму, Content-Type: application/json. Повернення будь-якого 2xx вважається підтвердженням; для 5xx буде виконано повторні спроби з експоненційною затримкою протягом приблизно 5 хвилин.

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

HTTP	`error.code`	Значення
400	`bad_request`	Тіло запиту не пройшло перевірку Zod (відсутній `url`, неправильний тип …).
401	`unauthorized`	Відсутній або недійсний `Authorization: Bearer …`.
402	(x402)	Недостатній баланс платформи, повертається envelope з вимогою оплати 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: Invalid 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 }； після завершення завдання платформа виконає POST повного результату до вашого 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

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

Coding

Інші посібники

Посібник з інтеграції API рендерингу вебсторінок WebExtrator

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

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

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

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

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

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

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

Приклади

cURL

Python (requests)

Node.js (fetch)

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

Примусовий обхід кешу

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

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

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

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

​Структура Cookie

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

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

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

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

​Приклади

​cURL

​Python (requests)

​Node.js (fetch)

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

​Примусовий обхід кешу

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

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

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

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

Структура Cookie

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

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

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

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

Приклади

cURL

Python (requests)

Node.js (fetch)

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

Примусовий обхід кешу

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