浏览器任务

本页内容

截图、HTML 与 SPA 提取均为同步计费请求：请求体上限 1 MiB，通过校验后在入队前扣除 1 credit；默认随机 User-Agent，并支持可信代理池与动态地区路由。

POST/screenshot

捕获页面截图

页面截图 · 国家/地区代理

请求

请求头

字段	类型	说明
`x-api-key`必填	`string`	控制台创建的完整 API Key。
`content-type`必填	`application/json`	请求体必须是 JSON。

请求体

字段	类型	说明
`url`必填	`string`	必须是可访问的 HTTP(S) URL，仅支持 80 和 443 端口。
`viewport`	`{ width: number; height: number }`	截图视口大小。
`fullPage`	`boolean`	是否截取整页，默认 true；传 selector 时只截取匹配元素。
`selector`	`string`	只截取首个匹配元素；未匹配时返回 422 CONTENT_SELECTOR_NOT_FOUND。
`waitUntil`	`"load" \| "domcontentloaded" \| "networkidle"`	默认 load。仅接受 load、domcontentloaded、networkidle；其他值会按 load 处理。 `domcontentloaded` 等待 DOMContentLoaded，HTML 已解析，不等待图片等次要资源；推荐用于 HTML 内容提取。 `load` 等待 window.load，页面及图片、样式等依赖资源完成加载。 `networkidle` 等待至少 500ms 没有网络连接。长轮询、统计请求、懒加载资源可能导致超时。
`timeoutMs`	`number`	正数且不超过 3,600,000；其他值使用服务端默认超时。
`locale`	`string`	浏览器 locale，例如 en-US。
`timezoneId`	`string`	IANA 时区，例如 Asia/Shanghai。
`geolocation`	`{ latitude: number; longitude: number }`	可选地理位置。
`proxy`	`proxy`	自定义代理；与 countryCode 不能同时传入。
`countryCode`	`string`	托管代理地区。使用 GLOBAL 从 15 个热门地区中随机分配动态出口；指定二字国家/地区码时优先使用可信代理，不可用时由动态代理兜底。不传时随机使用可信代理，不能与自定义 proxy 同时传入。
`userAgentMode`	`"custom" \| "random"`	设为 random 时由服务端从 User-Agent 库随机选择；未传 User-Agent 时默认使用 random。
`userAgentOs`	`"windows" \| "macos"`	随机模式使用的操作系统，默认 windows。
`fingerprint`	`fingerprint`	浏览器指纹设置。不传时所有项目默认随机，并保持操作系统、GPU、CPU、内存、字体和设备信号一致。
`userAgent`	`string`	覆盖默认 User-Agent。
`cookies`	`cookies[]`	预写入浏览器上下文的 Cookie 列表。

响应

200: image/png返回 PNG 二进制流。
400: application/jsonJSON、URL、cookies、代理、地区或随机 User-Agent 参数非法；请求体超过 1 MiB 也按无效 JSON 处理。
401: application/json缺少或错误的 x-api-key。
402: application/json余额不足，返回 INSUFFICIENT_CREDITS、balance 与 requiredCredits。
422: application/jsonselector 未匹配或 Worker 拒绝任务参数。
429: application/json任务触发限流。
502: application/json代理不可达、目标站点返回错误，或结果超过内联大小限制。
503: application/json队列、Worker、托管代理或 User-Agent 资源不可用。
504: application/json任务、导航、目标站点或代理连接超时。
500: application/json未归类的任务执行失败。

请求示例

curl -sS -X POST "https://api.adscrawl.net/screenshot" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url":"https://example.com","viewport":{"width":1440,"height":900},"fullPage":true,"waitUntil":"load","countryCode":"GLOBAL","userAgentMode":"random","userAgentOs":"windows"}' \
  --output page.png

{
  "url": "https://example.com",
  "viewport": { "width": 1440, "height": 900 },
  "fullPage": true,
  "waitUntil": "load",
  "locale": "zh-CN",
  "timezoneId": "Asia/Shanghai",
  "countryCode": "GLOBAL",
  "userAgentMode": "random",
  "userAgentOs": "windows"
}

响应示例

HTTP/1.1 200 OK
Content-Type: image/png

<binary PNG stream>

{
  "error": "countryCode is not supported",
  "code": "INVALID_COUNTRY_CODE"
}

{
  "error": "Dynamic country/region routing is unavailable",
  "code": "DYNAMIC_PROXY_NOT_CONFIGURED"
}

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "balance": 0,
  "requiredCredits": 1
}

POST/html

HTML / Readability 提取 · 国家/地区代理

请求

请求头

字段	类型	说明
`x-api-key`必填	`string`	控制台创建的完整 API Key。
`content-type`必填	`application/json`	请求体必须是 JSON。

请求体

字段	类型	说明
`url`必填	`string`	目标页面 URL，仅支持 80 和 443 端口。
`contentMode`	`"html" \| "markdown" \| "json"`	默认 html。markdown / json 会调用 Readability 提取正文。
`selector`	`string`	先等待首个匹配元素。contentMode=html 时仅返回该元素 HTML；markdown/json 基于该元素执行 Readability。未匹配时返回 422。
`waitUntil`	`"load" \| "domcontentloaded" \| "networkidle"`	默认 load。HTML 正文提取通常推荐 domcontentloaded；networkidle 可能被长轮询或统计请求拖慢。 `domcontentloaded` 等待 DOMContentLoaded，HTML 已解析，不等待图片等次要资源；推荐用于 HTML 内容提取。 `load` 等待 window.load，页面及图片、样式等依赖资源完成加载。 `networkidle` 等待至少 500ms 没有网络连接。长轮询、统计请求、懒加载资源可能导致超时。
`timeoutMs`	`number`	正数且不超过 3,600,000；其他值使用服务端默认超时。
`viewport`	`{ width: number; height: number }`	页面视口。
`locale`	`string`	浏览器 locale。
`timezoneId`	`string`	IANA 时区。
`geolocation`	`{ latitude: number; longitude: number }`	可选地理位置。
`proxy`	`proxy`	自定义代理；与 countryCode 不能同时传入。
`countryCode`	`string`	托管代理地区。使用 GLOBAL 从 15 个热门地区中随机分配动态出口；指定二字国家/地区码时优先使用可信代理，不可用时由动态代理兜底。不传时随机使用可信代理，不能与自定义 proxy 同时传入。
`userAgentMode`	`"custom" \| "random"`	设为 random 时由服务端从 User-Agent 库随机选择；未传 User-Agent 时默认使用 random。
`userAgentOs`	`"windows" \| "macos"`	随机模式使用的操作系统，默认 windows。
`fingerprint`	`fingerprint`	浏览器指纹设置。不传时所有项目默认随机，并保持操作系统、GPU、CPU、内存、字体和设备信号一致。
`userAgent`	`string`	覆盖默认 User-Agent。
`cookies`	`cookies[]`	预置 Cookie。

响应

200: text/html; charset=utf-8contentMode=html 时返回完整页面 HTML；传 selector 时仅返回匹配元素 HTML。
200: text/markdown; charset=utf-8contentMode=markdown 时返回正文 Markdown。
200: application/jsoncontentMode=json 时返回 Readability 结构化结果。
400: application/jsonJSON、URL、contentMode、cookies、代理、地区或随机 User-Agent 参数非法。
401: application/json缺少或错误的 x-api-key。
402: application/json余额不足，code 为 INSUFFICIENT_CREDITS。
422: application/jsonselector 未匹配、无法提取正文或 Worker 参数无效。
429: application/json任务触发限流。
502: application/json代理、目标站点或结果大小错误。
503: application/json队列、Worker、托管代理或 User-Agent 资源不可用。
504: application/json任务、导航、目标站点或代理连接超时。
500: application/json未归类的任务执行失败。

请求示例

curl -sS -X POST "https://api.adscrawl.net/html" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url":"https://example.com/article","contentMode":"json","waitUntil":"domcontentloaded","countryCode":"GLOBAL","userAgentMode":"random","userAgentOs":"windows"}'

{
  "url": "https://example.com/article",
  "contentMode": "json",
  "waitUntil": "domcontentloaded",
  "viewport": { "width": 1280, "height": 720 },
  "locale": "en-US",
  "countryCode": "GLOBAL",
  "userAgentMode": "random",
  "userAgentOs": "windows"
}

响应示例

{
  "title": "Example Article",
  "byline": "OpenAI",
  "excerpt": "A concise article summary.",
  "siteName": "Example",
  "lang": "en",
  "dir": null,
  "content": "<div><p>Readable body...</p></div>",
  "textContent": "Readable body...",
  "length": 2487,
  "publishedTime": null
}

# Example Article

Readable body...

- key point one
- key point two

{
  "error": "Readable article content was not found",
  "code": "READABILITY_CONTENT_NOT_FOUND"
}

{
  "error": "countryCode is not supported",
  "code": "INVALID_COUNTRY_CODE"
}

{
  "error": "Dynamic country/region routing is unavailable",
  "code": "DYNAMIC_PROXY_NOT_CONFIGURED"
}

GET/spa-extract/templates

列出可用 SPA 模板

请求

请求头

字段	类型	说明
`x-api-key`必填	`string`	控制台创建的完整 API Key。

响应

200: application/json返回当前启用模板及其输入、默认值和输出字段。
401: application/json缺少或错误的 x-api-key。
500: application/json模板目录读取失败。

请求示例

curl -sS "https://api.adscrawl.net/spa-extract/templates" \
  -H "x-api-key: YOUR_API_KEY"

响应示例

{
  "templates": [
    {
      "id": "similarweb-overview",
      "name": "SimilarWeb Website Overview",
      "description": "Get public website traffic, engagement, and ranking metrics from SimilarWeb.",
      "urlPattern": "^https://www\\.similarweb\\.com/website/[^/?#]+/?(?:[?#].*)?$",
      "exampleUrl": "https://www.similarweb.com/website/dolphin-anty.com/#overview",
      "version": 5,
      "updatedAt": "2026-07-18T14:07:33.000Z",
      "outputFields": [
        "avgVisitDuration",
        "avgVisitDurationSeconds",
        "bounceRate",
        "categoryRank",
        "countryRank",
        "globalRank",
        "pagesPerVisit",
        "period",
        "targetDomain",
        "totalVisits",
        "totalVisitsDisplay"
      ],
      "waitUntil": "domcontentloaded",
      "input": {
        "type": "domain",
        "example": "dolphin-anty.com",
        "urlTemplate": "https://www.similarweb.com/website/{value}/#overview"
      },
      "catalog": {
        "category": "analytics",
        "featured": true,
        "keywords": ["traffic", "rank", "website analytics", "流量", "排名", "网站分析"]
      }
    }
  ]
}

POST/spa-extract

SPA 页面数据提取

请求

请求头

字段	类型	说明
`x-api-key`必填	`string`	控制台创建的完整 API Key。
`content-type`必填	`application/json`	请求体必须是 JSON。

请求体

字段	类型	说明
`url`	`string`	目标 SPA 的完整 HTTP(S) URL，仅支持 80 和 443 端口。Google Trends 推荐使用 keyword；为兼容旧客户端，只有 keyword 字段完全缺省时，url 才可为纯关键词或 Trends explore URL，后者只读取 q 查询参数。显式传 keyword:null、数字或空字符串会返回 INVALID_KEYWORD，不会回退到 url。keyword 与 url 同时提供时，url 必须是规范 Trends explore URL。SimilarWeb 必须传完整页面 URL，不能只传域名。
`keyword`	`string`	google-trends-explore 的推荐输入。使用逗号分隔 1-5 个互不重复的非空关键词，每个最多 100 个 Unicode 字符；服务端据此生成规范 Trends URL。只有字段完全缺省时才兼容从 url 读取；显式传 null、数字或空字符串会返回 INVALID_KEYWORD。若同时传 url，url 必须是规范 Trends explore URL。
`mode`	`"inspect" \| "extract"`	inspect 返回页面检查结果；extract 按 fields 或模板输出数据。
`template`	`string`	可选站点模板标识。chrome-web-store-app-info 在页面 listing 不可用时，会在同一个 60 秒总预算内尝试 CRX2/CRX3 manifest fallback；CRX 子阶段最多使用 20 秒，并至少为 Worker 保留 15 秒。只接受签名验证通过、且开发者公钥导出的 CRX ID 与请求扩展 ID 一致的 CRX2/CRX3，裸 ZIP 会被拒绝。HTTP/HTTPS 代理由 API 获取 CRX，SOCKS 代理继续由 Worker 获取。fallback 不新增公开错误码。
`parameters`	`object`	所选模板声明的参数。
`waitUntil`	`"load" \| "domcontentloaded" \| "networkidle"`	自定义提取默认 domcontentloaded；使用站点模板时优先采用请求值，否则采用模板值，再回退到 domcontentloaded。 `domcontentloaded` 等待 DOMContentLoaded，HTML 已解析，不等待图片等次要资源；推荐用于 HTML 内容提取。 `load` 等待 window.load，页面及图片、样式等依赖资源完成加载。 `networkidle` 等待至少 500ms 没有网络连接。长轮询、统计请求、懒加载资源可能导致超时。
`waitFor`	`waitFor`	等待指定元素或文本出现。
`actions`	`actions[]`	可选页面交互步骤，例如点击、填写、滚动或等待。
`fields`	`Record<string, field>`	extract 模式下需要提取的 DOM 或网络字段。
`schema`	`Record<string, string \| field> \| { properties: Record<string, string \| field> }`	仅在 fields 缺失时作为旧版字段选择器别名使用；字符串值视为 DOM selector。它不会校验响应 JSON，也不会返回 schemaValid/schemaErrors。
`timeoutMs`	`number`	正数且不超过 3,600,000；其他值使用服务端默认超时。
`viewport`	`{ width: number; height: number }`	页面视口。
`locale`	`string`	浏览器 locale；未传时可跟随可信代理。
`timezoneId`	`string`	IANA 时区；未传时可跟随可信代理。
`geolocation`	`{ latitude: number; longitude: number }`	可选地理位置。
`proxy`	`proxy`	自定义代理；与 countryCode 不能同时传入。
`countryCode`	`string`	托管代理地区。使用 GLOBAL 从 15 个热门地区中随机分配动态出口；指定二字国家/地区码时优先使用可信代理，不可用时由动态代理兜底。不传时随机使用可信代理，不能与自定义 proxy 同时传入。
`userAgentMode`	`"custom" \| "random"`	设为 random 时由服务端从 User-Agent 库随机选择；未传 User-Agent 时默认使用 random。
`userAgentOs`	`"windows" \| "macos"`	随机模式使用的操作系统，默认 windows。
`fingerprint`	`fingerprint`	浏览器指纹设置。不传时所有项目默认随机，并保持操作系统、GPU、CPU、内存、字体和设备信号一致。
`userAgent`	`string`	覆盖默认 User-Agent。
`cookies`	`cookies[]`	预置 Cookie。google-trends-explore 会忽略缺省、null 或空数组；任何非空或格式非法的 cookies 都返回 400 INVALID_TRENDS_COOKIES。

响应

200: application/json返回检查结果或提取后的结构化数据。Google Trends 成功响应顶层额外返回 source（sunbrowser/cache）、cached、stale、collectedAt（RFC3339Nano）和 attempts。Chrome Web Store manifest fallback 返回与页面 listing 提取相同的字段，并设置 categoryZh=非公开、categoryEn=Unlisted；CRX 整包响应上限 32 MiB，ZIP central directory 上限 8 MiB、ZIP 条目数上限 8,192，选取的 manifest.json 与 _locales/*/messages.json 元数据文件数上限 128、累计未压缩元数据大小上限 8 MiB，manifest.json 与单个 locale messages.json 各自上限 1 MiB，manifest 选中最大图标的未压缩大小上限 2 MiB，最终结果上限 4 MiB。图标只接受来自签名及扩展 ID 已匹配 CRX 的 PNG、JPEG、WebP 或 GIF，拒绝 SVG。
400: application/jsonURL、Google Trends 关键词、代理、地区或随机 User-Agent 参数无效；Google Trends 请求携带非空或格式非法 cookies 时 code 为 INVALID_TRENDS_COOKIES，显式 keyword:null、数字或空字符串时 code 为 INVALID_KEYWORD。
401: application/json缺少或错误的 x-api-key。
402: application/json余额不足，code 为 INSUFFICIENT_CREDITS。
404: application/jsonChrome Web Store 页面 listing 不可用且 CRX manifest fallback 未能恢复时，继续使用现有 code CHROME_WEB_STORE_LISTING_UNAVAILABLE；fallback 不新增公开错误码。
422: application/json必填字段缺失、模板/字段配置无效或 Worker 拒绝任务。
429: application/json任务限流，或 Google Trends 上游返回 429。
502: application/json代理/目标站点失败、Trends 数据无效或所有候选身份均失败。
503: application/json队列、Worker、托管资源不可用，或 Trends 身份计划已过期。
504: application/json任务、导航、代理连接超时，或未观察到 Trends 响应。
500: application/json未归类的任务执行失败。

请求示例

curl -sS -X POST "https://api.adscrawl.net/spa-extract" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url":"https://example.com/dashboard","mode":"extract","waitUntil":"domcontentloaded","waitFor":{"selector":"h1","timeoutMs":15000},"fields":{"title":{"source":"dom","selector":"h1","parse":"string"}},"countryCode":"GLOBAL","userAgentMode":"random","userAgentOs":"windows"}'

{
  "url": "https://example.com/dashboard",
  "mode": "extract",
  "waitUntil": "domcontentloaded",
  "waitFor": { "selector": "h1", "timeoutMs": 15000 },
  "fields": {
    "title": { "source": "dom", "selector": "h1", "parse": "string" }
  },
  "countryCode": "GLOBAL",
  "userAgentMode": "random",
  "userAgentOs": "windows"
}

{
  "template": "similarweb-overview",
  "url": "https://www.similarweb.com/website/dolphin-anty.com/#overview",
  "countryCode": "GLOBAL"
}

{
  "template": "google-trends-explore",
  "keyword": "adspower,playwright"
}

{
  "template": "google-trends-explore",
  "url": "https://trends.google.com/trends/explore?q=adspower%2Cplaywright"
}

{
  "template": "chrome-web-store-app-info",
  "url": "https://chromewebstore.google.com/detail/example-extension/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "countryCode": "GLOBAL"
}

响应示例

{
  "mode": "extract",
  "page": {
    "url": "https://example.com/dashboard",
    "title": "Example Dashboard"
  },
  "data": {
    "title": "Example Dashboard"
  },
  "missingFields": []
}

{
  "mode": "extract",
  "page": {
    "url": "https://trends.google.com/trends/explore?q=adspower%2Cplaywright",
    "title": "Google Trends"
  },
  "data": {
    "averages": [
      { "query": "adspower", "extractedValue": 42 },
      { "query": "playwright", "extractedValue": 71 }
    ],
    "interestOverTime": []
  },
  "missingFields": [],
  "source": "sunbrowser",
  "cached": false,
  "stale": false,
  "collectedAt": "2026-08-03T02:04:05.123456789Z",
  "attempts": 2
}

{
  "mode": "inspect",
  "page": {
    "url": "https://example.com/dashboard",
    "title": "Example Dashboard"
  },
  "candidates": {
    "dom": { "metrics": [], "tables": [] },
    "network": []
  },
  "suggestedPlan": {
    "fields": {},
    "schema": {
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
  }
}

捕获页面截图

请求

请求头

请求体

响应

请求示例

响应示例

HTML / Readability 提取 · 国家/地区代理

请求

请求头

请求体

响应

请求示例

响应示例

列出可用 SPA 模板

请求

请求头

响应

请求示例

响应示例

SPA 页面数据提取

请求

请求头

请求体

响应

请求示例

响应示例

基于值得信赖的浏览器构建您的工作流

基于值得信赖的浏览器
构建您的工作流