> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adscrawl.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 浏览器任务：HTML、截图与数据提取

> 同步且按积分计费的请求，启动完整浏览器并返回渲染后的 HTML、截图或结构化数据，无需管理会话。

浏览器任务是获取任意 URL 渲染内容的最简单方式。每次请求都会启动一个全新的 Chromium 实例，通过住宅代理访问目标页面，并同步返回结果，无需创建会话，也无需清理。积分在请求验证通过后、浏览器启动前扣除，因此格式错误的请求体不会消耗积分。请求体最大限制为 1 MiB，`timeoutMs` 可设置最长 3,600,000 毫秒（一小时），以处理缓慢或复杂的页面。

## 任务类型

AdsCrawl 提供三种浏览器任务端点，每种针对不同输出优化：

### HTML / Markdown

`POST /html` 渲染目标页面并以三种内容模式之一返回：

* **`html`**（默认）：完整的渲染页面 HTML，或在设置了 `selector` 时仅返回匹配元素
* **`markdown`**：通过 Readability 提取的文章内容，转换为 Markdown
* **`json`**：结构化的 Readability 文章对象，包含 `title`、`byline`、`excerpt`、`textContent`、`length` 等字段

大多数 HTML 提取任务使用 `waitUntil: "domcontentloaded"` 即可，它比等待图片和样式表加载更快。仅在页面加载后通过 XHR 获取所需内容时，才切换到 `"networkidle"`。

### 截图

`POST /screenshot` 捕获渲染页面的 PNG 图像，并直接以 `image/png` 格式流式返回。关键选项：

* **`fullPage: true`**（默认）：捕获整个可滚动页面
* **`selector`**：仅捕获匹配 CSS 选择器的第一个元素；如果选择器未匹配则返回 `422 CONTENT_SELECTOR_NOT_FOUND`
* **`viewport`**：设置宽度和高度以控制截图前的渲染视口

### SPA 提取

`POST /spa-extract` 从动态单页应用中提取结构化字段。你可以自定义字段，在提取前执行页面操作（点击、填写、滚动），并使用 `waitFor` 等待元素或文本出现。提供两种模式：

* **`inspect`**：返回页面候选字段和建议的字段方案，不消耗额外积分
* **`extract`**：返回你在 `fields` 映射或命名 `template` 中定义的数据

AdsCrawl 维护一个现成站点模板目录（例如 `similarweb-overview`、`google-trends-explore`、`chrome-web-store-app-info`）。通过 `GET /spa-extract/templates` 获取完整列表。

## 积分机制

每个浏览器任务请求扣除 1 积分。扣费发生在**验证通过后**（因此错误请求免费）但**浏览器启动前**（因此导航失败仍会消耗 1 积分）。在执行大批量任务前，请在 [dashboard](https://app.adscrawl.net/dashboard/) 中检查余额。

## 代理行为

每个浏览器任务都通过代理运行。你可以通过两个可选字段控制使用的代理：

| 设置 | 行为 |
| - | - |
| 两个字段均未设置 | 自动分配随机可信住宅代理 |
| `countryCode: "US"` | 托管代理优先选择该区域的可靠出口，并动态回退 |
| `countryCode: "GLOBAL"` | 动态出口在 15 个热门地区之间轮换 |
| `proxy` 对象 | 使用你自己的 HTTP 或 SOCKS5 代理服务器 |

`countryCode` 和 `proxy` 互斥，只能传入其中一个，不能同时传入两者。

## 请求限制

| 限制 | 值 |
| - | - |
| 请求体 | 最大 1 MiB |
| `timeoutMs` | 1 - 3,600,000 毫秒 |
| 支持的端口 | 仅 80 和 443 |

<Note>
  浏览器任务是**无状态的**，每次请求都会创建一个全新的浏览器上下文，不保留之前的访问记录。如果你需要在多个页面之间保持 cookies、local storage 或登录会话，请改用 [Remote CDP](/zh/concepts/remote-cdp) 或 [Cloud Browsers](/zh/concepts/cloud-browsers)。
</Note>

## API 参考

<CardGroup cols={3}>
  <Card title="POST /html" icon="code" href="/zh/api-reference/html">
    从任意 URL 获取渲染后的 HTML、Markdown 或结构化文章 JSON。
  </Card>

  <Card title="POST /screenshot" icon="camera" href="/zh/api-reference/screenshot">
    捕获整页或元素级别的 PNG 截图。
  </Card>

  <Card title="POST /spa-extract" icon="table" href="/zh/api-reference/spa-extract">
    从动态 SPA 中提取结构化字段，支持模板和操作。
  </Card>
</CardGroup>