> ## 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.

# API Schema 参考：所有端点共享的类型

> AdsCrawl 所有端点共享的可复用 Schema 参考定义，涵盖 browserSettings、proxy、fingerprint、cookies、waitFor、field 与 actions。在开始构建之前掌握这些共享类型，可帮助你一致且正确地配置浏览器任务、CDP 会话与云浏览器环境。

这些 schema 出现在多个 AdsCrawl 端点中。本页面将每个 schema 集中定义一次，避免在每个端点参考中重复。在开始构建之前理解 `browserSettings`、`fingerprint`、`proxy`、`cookies`、`waitFor`、`field` 和 `actions`，可以让你一致且正确地配置浏览器任务、CDP 会话和云浏览器。

***

## `browserSettings`

在 CDP 会话和云浏览器之间共享的浏览器配置。省略地区时会使用随机可信代理；如果需要确定性路由，请显式传入 `GLOBAL`、地区代码或自定义 `proxy` 对象。

<ParamField body="viewport" type="object">
  浏览器窗口大小。

  <Expandable title="viewport 字段">
    <ParamField body="width" type="number" required>
      视口宽度，单位为像素。
    </ParamField>

    <ParamField body="height" type="number" required>
      视口高度，单位为像素。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="locale" type="string">
  浏览器语言环境，例如 `"en-US"`。
</ParamField>

<ParamField body="timezoneId" type="string">
  IANA 时区标识符，例如 `"Asia/Shanghai"`。
</ParamField>

<ParamField body="geolocation" type="object">
  注入浏览器的可选地理位置坐标。

  <Expandable title="geolocation 字段">
    <ParamField body="latitude" type="number" required>
      纬度，以十进制度数表示。
    </ParamField>

    <ParamField body="longitude" type="number" required>
      经度，以十进制度数表示。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="proxy" type="object">
  自定义代理配置。不能与 `countryCode` 同时使用。请参阅下方的 [`proxy` schema](#proxy)。
</ParamField>

<ParamField body="countryCode" type="string">
  托管代理地区。使用 `"GLOBAL"` 可自动选择热门地区，或使用两位国家代码（例如 `"FR"`）以优先选择该地区的可信代理并支持动态回退。不能与 `proxy` 同时使用。
</ParamField>

<ParamField body="userAgent" type="string">
  覆盖默认的 User-Agent 字符串。
</ParamField>

<ParamField body="userAgentMode" type="&#x22;custom&#x22; | &#x22;random&#x22;">
  设置为 `"random"` 可让服务器从其库中选择 User-Agent。未提供 User-Agent 的请求默认使用 `"random"`。
</ParamField>

<ParamField body="userAgentOs" type="&#x22;windows&#x22; | &#x22;macos&#x22;">
  随机 User-Agent 模式使用的操作系统。默认为 `"windows"`。
</ParamField>

<ParamField body="fingerprint" type="object">
  浏览器指纹设置。在 CDP 上下文中省略时，`canvas` 和 `webGlImage` 默认为 `"real"`，其他信号使用一致的随机化配置。请参阅下方的 [`fingerprint` schema](#fingerprint)。
</ParamField>

<ParamField body="cookies" type="cookies[]">
  在会话启动前注入浏览器上下文的 Cookie。请参阅下方的 [`cookies[]` schema](#cookies)。
</ParamField>

### 示例

```json theme={null}
{
  "viewport": { "width": 1440, "height": 900 },
  "locale": "en-US",
  "timezoneId": "America/New_York",
  "countryCode": "US",
  "userAgentMode": "random",
  "userAgentOs": "macos",
  "fingerprint": {
    "canvas": "random",
    "webRtc": "forward"
  }
}
```

***

## `fingerprint`

控制浏览器指纹信号以降低被检测的风险。每个字段都是可选的。浏览器任务中省略的字段默认使用 `"random"`。CDP `browserSettings` 中省略时，`canvas` 和 `webGlImage` 设置为 `"real"`，其他信号从一致的随机化配置生成。

<Warning>
  当 `webGl` 为 `"real"` 时，不能将 `webGpu` 或 `hardware` 设置为 `"random"`。这三个信号必须保持一致。
</Warning>

| 字段 | 可接受的值 | 说明 |
| - | - | - |
| `webRtc` | `"forward" \| "real" \| "disabled"` | `"forward"` 使用代理出口地址。旧值 `"random"` 被接受为 `"forward"` 的别名。 |
| `webGl` | `"random" \| "real"` | 伪造或保留 WebGL 供应商和渲染器元数据。 |
| `webGpu` | `"random" \| "real" \| "disabled"` | `"random"` 模式下，遵循 WebGL GPU 配置。 |
| `webGlImage` | `"random" \| "real"` | 控制 WebGL 图像渲染噪声。 |
| `canvas` | `"random" \| "real"` | 添加或抑制 canvas 指纹噪声。 |
| `audioContext` | `"random" \| "real"` | 添加或抑制 audio context 指纹噪声。 |
| `clientRects` | `"random" \| "real"` | 添加或抑制布局测量噪声。 |
| `speechVoices` | `"random" \| "real"` | 返回与操作系统匹配或真实的语音列表。 |
| `fonts` | `"random" \| "real"` | 返回与操作系统匹配或真实的已安装字体列表。 |
| `hardware` | `"random" \| "real"` | 将 CPU 线程数和设备内存作为匹配对生成。 |
| `doNotTrack` | `"random" \| "enabled" \| "disabled"` | 控制 DNT 请求头偏好。 |

### 示例

```json theme={null}
{
  "webRtc": "forward",
  "webGl": "random",
  "webGpu": "random",
  "canvas": "random",
  "audioContext": "random",
  "fonts": "random",
  "hardware": "random",
  "doNotTrack": "disabled"
}
```

***

## `proxy`

用于路由浏览器流量的自定义代理配置。提供 `server` URL 形式或拆分形式（`protocol` + `host` + `port`），切勿同时使用两者。

<Warning>
  `username` 和 `password` 必须同时提供。对于无需认证的代理，请同时省略两者。切勿将凭据嵌入 `server` URL 中。
</Warning>

<ParamField body="server" type="string">
  完整的代理 URL，例如 `"http://host:port"` 或 `"socks5://host:port"`。必须包含显式端口。不能与 `host` 同时使用。请勿嵌入凭据、路径、查询字符串或片段。
</ParamField>

<ParamField body="protocol" type="&#x22;http&#x22; | &#x22;socks5&#x22;">
  拆分形式的代理协议。
</ParamField>

<ParamField body="host" type="string">
  拆分形式的代理主机名。不能与 `server` 同时使用。
</ParamField>

<ParamField body="port" type="number | string">
  拆分形式的代理端口。接受从 1 到 65535 的整数或数字字符串。
</ParamField>

<ParamField body="username" type="string">
  代理认证用户名。必须与 `password` 同时提供。
</ParamField>

<ParamField body="password" type="string">
  代理认证密码。必须与 `username` 同时提供。
</ParamField>

### 示例

<CodeGroup>
  ```json URL form theme={null}
  {
    "server": "http://proxy.example.com:8080",
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  }
  ```

  ```json Split form (SOCKS5) theme={null}
  {
    "protocol": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  }
  ```

  ```json Unauthenticated theme={null}
  {
    "server": "http://proxy.example.com:8080"
  }
  ```
</CodeGroup>

***

## `cookies[]`

在导航开始前注入浏览器上下文的 Cookie 数组。每个条目都是一个具有以下字段的对象。

<ParamField body="name" type="string" required>
  Cookie 名称。
</ParamField>

<ParamField body="value" type="string" required>
  Cookie 值。
</ParamField>

<ParamField body="domain" type="string" required>
  目标域名，例如 `".example.com"`。包含前导点以匹配子域名。
</ParamField>

<ParamField body="path" type="string">
  Cookie 路径。默认为 `"/"`。
</ParamField>

<ParamField body="secure" type="boolean">
  当为 `true` 时，Cookie 仅通过 HTTPS 发送。
</ParamField>

<ParamField body="httpOnly" type="boolean">
  当为 `true` 时，Cookie 对客户端 JavaScript 不可访问。
</ParamField>

<ParamField body="hostOnly" type="boolean">
  当为 `true` 时，Cookie 绑定到确切主机而非子域名。
</ParamField>

<ParamField body="sameSite" type="string">
  SameSite 属性。可接受的值：`"Strict"`、`"Lax"`、`"None"`。
</ParamField>

<ParamField body="session" type="boolean">
  当为 `true` 时，Cookie 随会话过期，没有持久性过期时间。
</ParamField>

<ParamField body="expirationDate / expires / expiry" type="number">
  以 Unix 时间戳（秒）表示的持久性过期时间。这三个字段名称可以互换使用。
</ParamField>

### 示例

```json theme={null}
[
  {
    "name": "sid",
    "value": "<session-token>",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true,
    "sameSite": "Lax",
    "expirationDate": 1893456000
  }
]
```

***

## `waitFor`

指示浏览器在导航后或执行 `actions` 后暂停，直到页面上出现特定元素或文本。你可以在同一个对象中组合使用 `selector` 和 `text`。

<ParamField body="selector" type="string">
  CSS 选择器。浏览器等待第一个匹配的元素变为可见。
</ParamField>

<ParamField body="text" type="string">
  文本内容。浏览器等待第一个包含此文本的元素变为可见。
</ParamField>

<ParamField body="timeoutMs" type="number">
  最长等待时间，单位为毫秒。默认为 `15000`。无论提供什么值，都不会超过剩余的任务超时时间。
</ParamField>

### 示例

```json theme={null}
{
  "selector": "#search-results",
  "timeoutMs": 10000
}
```

***

## `field`（SPA 提取字段定义）

定义 `POST /spa-extract` 请求中要提取的单个字段。DOM 字段读取元素内容；网络字段从拦截到的 JSON 响应中捕获数据。

<ParamField body="source" type="&#x22;dom&#x22; | &#x22;network&#x22;" required>
  此字段的数据源。使用 `"dom"` 从页面 DOM 中读取，或使用 `"network"` 从网络请求中捕获匹配的 JSON 响应。
</ParamField>

<ParamField body="selector" type="string">
  标识目标元素的 CSS 选择器。`source: "dom"` 字段必填。
</ParamField>

<ParamField body="value" type="&#x22;text&#x22; | &#x22;html&#x22; | &#x22;attribute&#x22;">
  DOM 读取模式。默认为 `"text"`。使用 `"html"` 获取元素内部 HTML，或使用 `"attribute"` 读取特定属性。
</ParamField>

<ParamField body="attribute" type="string">
  当 `value` 为 `"attribute"` 时要读取的属性名称。例如 `"href"` 或 `"data-id"`。
</ParamField>

<ParamField body="urlIncludes" type="string">
  用于匹配 `source: "network"` 字段响应 URL 的子字符串。使用最近匹配的响应。
</ParamField>

<ParamField body="path" type="string">
  从匹配的网络响应体中提取值的 JSONPath 表达式。例如 `"$.data.metrics[0].value"`。
</ParamField>

<ParamField body="multiple" type="boolean">
  当为 `true` 时，字段返回所有匹配 DOM 元素的数组，而不仅仅是第一个。
</ParamField>

<ParamField body="parse" type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;integer&#x22; | &#x22;boolean&#x22; | &#x22;json&#x22;">
  在返回之前，将提取的原始值强制转换为指定类型。
</ParamField>

<ParamField body="regex" type="string">
  应用于提取值的正则表达式。当模式包含捕获组时，组 1 将作为字段值返回。
</ParamField>

<ParamField body="required" type="boolean">
  当为 `true` 时，缺失或不匹配的字段会导致端点返回 `422 SPA_REQUIRED_FIELDS_MISSING`，而不是返回 `null`。
</ParamField>

### 示例

<CodeGroup>
  ```json DOM field theme={null}
  {
    "source": "dom",
    "selector": "h1.product-title",
    "value": "text",
    "required": true
  }
  ```

  ```json DOM attribute field theme={null}
  {
    "source": "dom",
    "selector": "meta[name='description']",
    "value": "attribute",
    "attribute": "content"
  }
  ```

  ```json Network field theme={null}
  {
    "source": "network",
    "urlIncludes": "/api/v2/metrics",
    "path": "$.data.metrics[0].value",
    "parse": "number",
    "required": true
  }
  ```

  ```json Multiple elements theme={null}
  {
    "source": "dom",
    "selector": "ul.results li",
    "value": "text",
    "multiple": true
  }
  ```
</CodeGroup>

***

## `actions[]`

在 `POST /spa-extract` 中提取开始前执行的有序页面交互数组。每个元素都是一个带有 `type` 字段的对象，决定执行哪个操作。每个交互步骤的上限为 30 秒。

<Accordion title="wait — 暂停执行">
  暂停执行固定毫秒数。

  ```json theme={null}
  { "type": "wait", "milliseconds": 2000 }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"wait"`。
  </ParamField>

  <ParamField body="milliseconds" type="number" required>
    暂停时长。可接受范围：`0` 到 `30000`。
  </ParamField>
</Accordion>

<Accordion title="waitForSelector — 等待元素">
  暂停直到第一个匹配 CSS 选择器的元素变为可见。

  ```json theme={null}
  { "type": "waitForSelector", "selector": "#content", "timeoutMs": 8000 }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"waitForSelector"`。
  </ParamField>

  <ParamField body="selector" type="string" required>
    要等待的 CSS 选择器。
  </ParamField>

  <ParamField body="timeoutMs" type="number">
    最长等待时间，单位为毫秒。省略时默认为该步骤的 30 秒上限。
  </ParamField>
</Accordion>

<Accordion title="click — 点击元素">
  点击第一个匹配 CSS 选择器的元素。

  ```json theme={null}
  { "type": "click", "selector": "button.load-more" }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"click"`。
  </ParamField>

  <ParamField body="selector" type="string" required>
    要点击元素的 CSS 选择器。
  </ParamField>
</Accordion>

<Accordion title="fill — 填充输入框">
  清除目标输入元素并输入给定值。

  ```json theme={null}
  { "type": "fill", "selector": "input[name='q']", "value": "browser automation" }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"fill"`。
  </ParamField>

  <ParamField body="selector" type="string" required>
    要填充的输入元素的 CSS 选择器。
  </ParamField>

  <ParamField body="value" type="string" required>
    要输入到输入框的文本。
  </ParamField>
</Accordion>

<Accordion title="press — 按键">
  向第一个匹配 CSS 选择器的元素发送键盘按键。

  ```json theme={null}
  { "type": "press", "selector": "input[name='q']", "key": "Enter" }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"press"`。
  </ParamField>

  <ParamField body="selector" type="string" required>
    目标元素的 CSS 选择器。
  </ParamField>

  <ParamField body="key" type="string" required>
    要按的键，例如 `"Enter"`、`"Tab"` 或 `"ArrowDown"`。
  </ParamField>
</Accordion>

<Accordion title="scroll — 滚动页面或元素">
  将元素滚动到视图中，或按给定的像素偏移量滚动页面。

  ```json theme={null}
  { "type": "scroll", "y": 1200 }
  ```

  ```json theme={null}
  { "type": "scroll", "selector": ".lazy-section" }
  ```

  <ParamField body="type" type="string" required>
    必须为 `"scroll"`。
  </ParamField>

  <ParamField body="selector" type="string">
    CSS 选择器。提供时，匹配的元素将被滚动到视图中。
  </ParamField>

  <ParamField body="x" type="number">
    水平滚动偏移量，单位为像素。默认为 `0`。
  </ParamField>

  <ParamField body="y" type="number">
    垂直滚动偏移量，单位为像素。未提供 `selector` 时默认为 `800`。
  </ParamField>
</Accordion>

### 完整的 actions 示例

```json theme={null}
[
  { "type": "waitForSelector", "selector": "#cookie-banner button", "timeoutMs": 5000 },
  { "type": "click", "selector": "#cookie-banner button" },
  { "type": "fill", "selector": "input[name='q']", "value": "adscrawl api" },
  { "type": "press", "selector": "input[name='q']", "key": "Enter" },
  { "type": "waitForSelector", "selector": "#results", "timeoutMs": 10000 },
  { "type": "scroll", "y": 1600 }
]
```

***

## `cloudBrowser.runtime`

云浏览器端点返回的运行时状态对象。它描述了运行中或已停止的浏览器会话的当前生命周期状态。

<Warning>
  切勿自行构造 `connectUrl` 或 `cdpBaseUrl`，也不要将 API 密钥、Cookie 或代理凭据附加到这些 URL。始终使用 API 返回的确切 URL。如果响应中缺少 URL，请在继续之前查询当前状态。
</Warning>

<ResponseField name="runtimeKind" type="&#x22;neko&#x22; | &#x22;worker_cdp&#x22;">
  支撑此浏览器会话的运行时类型。`"neko"` 提供交互式浏览器并省略 `cdpBaseUrl`。`"worker_cdp"` 暴露 CDP 端点并可能包含 `cdpBaseUrl`。
</ResponseField>

<ResponseField name="status" type="&#x22;starting&#x22; | &#x22;running&#x22; | &#x22;stopping&#x22; | &#x22;stopped&#x22;" required>
  会话的当前生命周期状态。

  <Expandable title="状态值">
    | 值 | 含义 |
    | - | - |
    | `starting` | 会话正在配置中。运行配额已预留。 |
    | `running` | 会话处于活动状态。`connectUrl` 可能存在。 |
    | `stopping` | 已请求停止但尚未确认。运行配额仍被预留。 |
    | `stopped` | 会话已结束。运行配额已释放。 |
  </Expandable>
</ResponseField>

<ResponseField name="sessionId" type="string">
  活动会话标识符。在 `starting`、`running` 和 `stopping` 状态下存在。
</ResponseField>

<ResponseField name="expiresAt" type="string (RFC3339)">
  活动会话的过期时间。
</ResponseField>

<ResponseField name="connectUrl" type="string">
  打开交互式浏览器的直接 URL。仅当 `status` 为 `"running"` 且 `runtimeKind` 为 `"neko"` 时存在。需要配置文件所有者的登录会话，授权使用会话 Cookie，而非查看者的 `usr`/`pwd` URL 参数。
</ResponseField>

<ResponseField name="cdpBaseUrl" type="string">
  带有临时令牌的 CDP 基础 URL。仅由 `worker_cdp` 运行时返回。
</ResponseField>

<Note>
  `"starting"` 和 `"stopping"` 状态都计入用户的并发运行配额。`"stopping"` 会话尚未释放其槽位，请轮询 `GET /cloud-browsers/{id}` 直到返回 `"stopped"` 后再假设容量可用。
</Note>

### 响应示例

<CodeGroup>
  ```json Running (neko) theme={null}
  {
    "runtimeKind": "neko",
    "status": "running",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z",
    "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
  }
  ```

  ```json Stopped theme={null}
  {
    "runtimeKind": "neko",
    "status": "stopped"
  }
  ```

  ```json Stopping theme={null}
  {
    "runtimeKind": "neko",
    "status": "stopping",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z"
  }
  ```
</CodeGroup>

***

## Google Trends 结果元数据

成功的 `google-trends-explore` 响应在标准 SPA 结果之外返回的额外顶级字段。这些字段描述结果是从实时浏览器会话收集的，还是从服务器缓存提供的。

<ResponseField name="source" type="&#x22;sunbrowser&#x22; | &#x22;cache&#x22;" required>
  指示结果是从实时浏览器会话（`"sunbrowser"`）收集的，还是从服务器端缓存（`"cache"`）提供的。
</ResponseField>

<ResponseField name="cached" type="boolean" required>
  当此响应从缓存提供时为 `true`。
</ResponseField>

<ResponseField name="stale" type="boolean" required>
  当缓存结果已过期时为 `true`。响应已从缓存提供，但数据可能已过时。
</ResponseField>

<ResponseField name="collectedAt" type="string (RFC3339Nano)" required>
  结果实际收集的时间戳，格式为 RFC3339Nano。
</ResponseField>

<ResponseField name="attempts" type="integer" required>
  返回结果前进行的收集尝试次数。缓存命中响应始终报告 `0`。过期响应报告结果报告时已进行的尝试次数。
</ResponseField>

### 示例

```json theme={null}
{
  "source": "sunbrowser",
  "cached": false,
  "stale": false,
  "collectedAt": "2026-09-07T08:42:11.348291200Z",
  "attempts": 1
}
```