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` 表示不缓存本次响应。
`mode`	enum	❌	`sync`	`sync` 内联等待；`async` 立即返回 jobId，结果通过 `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": "2026-05-02T10:30:00.123Z",
  "finished_at": "2026-05-02T10:30:01.234Z",
  "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 毫秒时间戳。

异步响应

mode=async 时立即返回（HTTP 202）：

{ "jobId": "550e8400-...", "status": "queued" }

结果将通过 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`	同步队列拥挤，请重试或改用 `mode=async`。
500	`internal_error`	服务器端未处理异常（浏览器崩溃等），Worker 自动重试一次。

错误结构：

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": "...",
  "finished_at": "...",
  "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",
    "mode": "async",
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

立即返回 { "jobId": "...", "status": "queued" }；任务完成时平台会 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 忽略 mode。 同一 URL 的 sync 与 async 请求命中同一缓存条目，随意切换不会失效。
缓存 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)

异步 + 回调

强制绕过缓存

提示与坑