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	❌	—	異步模式下的回調地址，平台在任務完成時 `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
}

結果將通過 POST 推送到 callback_url（如果配置了），或者通過 /webextrator/tasks 主動查詢。

回調結構

平台 POST 與同步模式完全相同的 envelope 到 callback_url， 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 }；任務完成時平台會 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 適合傳統靜態頁。
快取 Key 忽略 async。 同一 URL 的同步與非同步請求命中同一快取條目，隨意切換不會失效。
快取 Key 忽略 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 音頻

網絡與數據

驗證碼

身份

代理

進階

WebExtrator 網頁渲染 API 集成指南

申請流程

鑑權

請求參數

同步響應

異步響應

回調結構

錯誤響應

示例

cURL

Python (requests)

Node.js (fetch)

非同步 + 回調

強制繞過快取

提示與坑

​申請流程

​鑑權

​請求參數

​Cookie 結構

​同步響應

​異步響應

​回調結構

​錯誤響應

​示例

​cURL

​Python (requests)

​Node.js (fetch)

​非同步 + 回調

​強制繞過快取

​提示與坑

申請流程

鑑權

請求參數

Cookie 結構

同步響應

異步響應

回調結構

錯誤響應

示例

cURL

Python (requests)

Node.js (fetch)

非同步 + 回調

強制繞過快取

提示與坑