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 토큰을 받아두세요.

로그인 또는 등록하지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: 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	❌	—	탐색 전에 주입할 쿠키, 구조는 아래와 같습니다.
`callback_url`	string	❌	—	비동기 모드에서의 콜백 주소, 플랫폼은 작업 완료 시 `POST`로 전체 결과를 이 주소로 전송합니다.
`bypass_cache`	boolean	❌	`false`	Redis 캐시 읽기를 건너뜁니다(하지만 이번 결과는 여전히 캐시에 기록됩니다).
`cache_ttl_seconds`	number	❌	`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
}

결과는 callback_url로 POST로 푸시됩니다(구성된 경우), 또는 /webextrator/tasks를 통해 수동으로 조회할 수 있습니다.

콜백 구조

플랫폼은 callback_url로 동기 모드와 완전히 동일한 envelope를 POST합니다, Content-Type: application/json입니다. 임의의 2xx를 반환하면 확인된 것으로 간주됩니다; 5xx는 지수 백오프를 통해 약 5분 동안 재시도됩니다.

오류 응답

HTTP	`error.code`	의미
400	`bad_request`	요청 본문이 Zod 검증을 통과하지 못했습니다(누락된 `url`, 잘못된 유형 등).
401	`unauthorized`	누락되었거나 유효하지 않은 `Authorization: Bearer …`.
402	(x402)	플랫폼 잔액 부족, x402 결제 요구 envelope 반환.
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 }를 반환합니다; 작업이 완료되면 플랫폼이 당신의 callback_url에 전체 결과를 POST합니다.

강제 캐시 우회

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

신원

프록시

고급

WebExtrator 웹 페이지 렌더링 API 통합 가이드

신청 절차

인증

요청 매개변수

쿠키 구조

동기 응답

비동기 응답

콜백 구조

오류 응답

예시

cURL

Python (requests)

Node.js (fetch)

비동기 + 콜백

강제 캐시 우회

팁과 주의사항

​신청 절차

​인증

​요청 매개변수

​쿠키 구조

​동기 응답

​비동기 응답

​콜백 구조

​오류 응답

​예시

​cURL

​Python (requests)

​Node.js (fetch)

​비동기 + 콜백

​강제 캐시 우회

​팁과 주의사항

신청 절차

인증

요청 매개변수

쿠키 구조

동기 응답

비동기 응답

콜백 구조

오류 응답

예시

cURL

Python (requests)

Node.js (fetch)

비동기 + 콜백

강제 캐시 우회

팁과 주의사항