Руководство по интеграции API рендеринга веб-страниц WebExtrator

POST https://api.acedata.cloud/webextrator/render WebExtrator API рендеринга веб-страниц — это сервис рендеринга веб-страниц на основе безголового 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 ещё больше ускорит работу.

Начало работы

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)

Асинхронный режим + обратный вызов

Принудительный обход кэша

Советы и подводные камни