> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-api/scrape.md).

# /scrape

了解如何使用 Oxylabs Web API /scrape 端点，以所需格式获取并解析任何网页。

该 `/v1/scrape` 该端点通过 URL 获取网页，自动处理无头浏览器渲染、代理轮换、访问挑战和本地化。它以 Markdown、HTML、JSON 或 PNG 截图形式返回结构化页面数据。

## 请求示例

该端点接受一个 JSON 负载，用于定义目标 URL、请求的输出格式、渲染选项和地理位置上下文。

```bash
curl https://webapi.oxylabs.io/v1/scrape \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{
      "url": "https://artificialintelligenceact.eu/implementation-timeline/",
      "output": ["markdown"]
  }'
```

### 请求参数

<table><thead><tr><th width="98">参数</th><th width="566">描述</th><th width="93">类型</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>url</code></mark></td><td>绝对 <code>http</code> / <code>https</code> 目标 URL。</td><td>字符串</td></tr><tr><td><code>output</code></td><td>响应格式： <code>Markdown</code>, <code>html</code>, <code>json</code>, <code>screenshot</code>。支持多个值。默认： <code>html</code></td><td>字符串数组</td></tr><tr><td><code>json</code></td><td>当 <code>output: ["json"]</code>，可通过以下方式用于自定义 AI 解析： <code>prompt</code> 或 <code>schema</code>。参见 <a href="/products/cn/web-api/scrape/ai-jie-xi.md">AI 解析</a>.</td><td>对象</td></tr><tr><td><code>location</code></td><td>两位 ISO 3166-1 alpha-2 国家代码（例如， <code>"US"</code>, <code>"DE"</code>, <code>"JP"</code>).</td><td>字符串</td></tr><tr><td><code>device</code></td><td>User-agent 和视口模拟： <code>"desktop"</code> （默认）或 <code>"mobile"</code>. </td><td>字符串</td></tr><tr><td><code>run_js</code></td><td>当设置为时启用 JavaScript 渲染 <code>true</code>。默认： <code>false</code>.</td><td>布尔值</td></tr></tbody></table>

&#x20;    — 必填参数。

<details>

<summary><strong><code>output</code></strong></summary>

该 `output` 字符串数组可在一次请求执行中获取多个输出格式。以下是组合输出请求示例：

```json
{
  "url": "https://example.com/product",
  "output": ["markdown", "json"],
  "json": {
    "prompt": "Extract the product name, stock status, and price as a number."
  }
}
```

<table data-header-hidden><thead><tr><th width="119"></th><th></th></tr></thead><tbody><tr><td><code>Markdown</code></td><td>将 DOM 树转换为干净、结构化的 Markdown，去除导航脚本和样式格式。针对导入 LLM 上下文窗口进行优化，以尽量减少 token 使用。</td></tr><tr><td><code>html</code></td><td>原始页面标记。需要标记本身（属性、嵌入的 JSON-LD、内联数据）时使用。不建议用于页面内容采集。</td></tr><tr><td><code>screenshot</code></td><td>完全渲染页面的 Base64 编码 PNG 图像。 <strong><code>run_js: true</code> 是必需的</strong>，否则请求将被拒绝。</td></tr><tr><td><code>json</code></td><td>与检索在同一请求中进行结构化提取（无需编写或维护选择器）。请将字段描述在一个 <code>prompt</code>，或通过一个精确固定其形状 <code>schema</code>。参见 <a href="/products/cn/web-api/scrape/ai-jie-xi.md">AI 解析</a>.</td></tr></tbody></table>

{% hint style="info" %}
**例外：** `video` 输出格式适用于 `/scrape/media` [专用爬虫](/products/cn/web-api/scrape/zhuan-yong-pa-chong.md).
{% endhint %}

</details>

<details>

<summary><strong><code>run_js</code></strong></summary>

在内容捕获之前执行页面自身的 JavaScript。

去掉 `run_js` 默认会为给定源路径使用最优执行路径。显式设置 `"run_js": true` 使用无头浏览器实例执行客户端脚本、动态 XHR 请求和单页应用（SPA）渲染。

```json
{
  "url": "https://example.com/spa-dashboard",
  "output": ["markdown"],
  "run_js": true
}
```

* **延迟影响：** 无头浏览器渲染会显著增加请求时长。请将客户端 HTTP 超时至少设置为 `150` 秒。当需要高吞吐量时， [异步交付](/products/cn/web-api/scrape/jiao-fu-mo-shi.md) 建议使用。
* **资源优化：** 请始终先尝试在不使用它的情况下获取内容。对于静态页面或 RSS/Atom 源，请传入 `"run_js": false` 以最大化请求吞吐量并最小化延迟。仅在必要时选择渲染。

</details>

<details>

<summary><strong><code>location</code></strong></summary>

地理定位会通过本地化代理出口节点路由请求。这样可确保本地化定价、语言变体和区域专属内容被正确提供。

```json
{
  "url": "https://example.com/pricing",
  "output": ["html"],
  "location": "DE",
  "check_empty_geo": true
}
```

{% hint style="info" %}
当使用 [专用爬虫](/products/cn/web-api/scrape/zhuan-yong-pa-chong.md)时，某些本地化参数的命名可能不同。
{% endhint %}

</details>

## 输出示例

成功请求会返回 HTTP `200 OK` 状态，并带有标准封装。位于其中的字段 `results[]` 对于未请求的输出格式将返回 `null`.

```json
{
  "status": 200,
  "results": [
    {
      "html": null,
      "markdown": "# Implementation Timeline\n\nProviders need to be compliant...",
      "screenshot": null,
      "json": null,
      "metadata": {
        "page": 1,
        "run_js": false,
        "url": "https://artificialintelligenceact.eu/implementation-timeline/"
      }
    }
  ],
  "params": {
    "url": "https://artificialintelligenceact.eu/implementation-timeline/",
    "output": ["markdown"],
    "json": { "schema": null, "prompt": null },
    "location": null,
    "device": "desktop",
    "run_js": null
  },
  "metadata": {
    "timestamp": 1787431568,
    "request_id": "7503078851572948993"
  }
}
```

{% hint style="info" %}
**`results[]` 对于未请求的输出格式返回的字段 `null`.** \
例如，请求 `["markdown"]` 会填充 `Markdown` 并使 `html`, `screenshot` 和 `json` 保持为 null。任何 [专用爬虫](/products/cn/web-api/scrape/zhuan-yong-pa-chong.md) 会将其结构化字段放在 `json`.
{% endhint %}

### 输出字典

<table><thead><tr><th width="208">字段</th><th>描述</th><th width="92">类型</th></tr></thead><tbody><tr><td><code>status</code></td><td>HTTP 状态码， <code>200</code> 成功时。参见 <a href="/products/cn/web-api/gu-zhang-pai-chu.md">错误代码</a>.</td><td>整数</td></tr><tr><td><code>results</code></td><td>针对所请求 URL 的一条记录。</td><td>数组</td></tr><tr><td><code>results[].markdown</code></td><td>如果请求了，则返回页面的 Markdown。 <code>null</code> 否则。</td><td>字符串</td></tr><tr><td><code>results[].html</code></td><td>如果请求了，则返回原始结果标记。 <code>null</code> 否则。</td><td>字符串</td></tr><tr><td><code>results[].json</code></td><td>来自 <a href="/products/cn/web-api/scrape/zhuan-yong-pa-chong.md">专用爬虫</a> 或 <a href="/products/cn/web-api/scrape/ai-jie-xi.md">AI 解析器</a>，如果请求了 <code>null</code> 否则。</td><td>对象</td></tr><tr><td><code>results[].screenshot</code></td><td>如果请求了，则返回 Base64 编码的图像字符串。 <code>null</code> 否则。</td><td>字符串</td></tr><tr><td><code>results[].metadata.url</code></td><td>重定向后的抓取目标 URL。</td><td>字符串</td></tr><tr><td><code>params</code></td><td>所有参数都用于应用默认值后的请求。</td><td>对象</td></tr><tr><td><code>metadata.timestamp</code></td><td>秒级 Unix 时间戳。</td><td>整数</td></tr><tr><td><code>metadata.request_id</code></td><td>此请求的标识符。 <strong>请在支持工单中包含它。</strong></td><td>字符串</td></tr></tbody></table>

## 延迟与并发

一次抓取会在 **秒级而非毫秒级的预算内渲染真实页面**。我们建议围绕这一点采用几项安全实践：

<table data-header-hidden><thead><tr><th width="123"></th><th></th></tr></thead><tbody><tr><td><strong>客户端超时</strong></td><td>150 秒是一个安全的默认值，而 10 秒超时可能会让本可成功的页面失败。对于更高吞吐量（例如媒体、较大的 SERP 批量运行等），如果存在客户端超时风险，请改用异步交付运行相同的爬虫，而不是阻塞请求。参见 <a href="/products/cn/web-api/scrape/jiao-fu-mo-shi.md">交付模式</a>.</td></tr><tr><td><strong>并发限制</strong></td><td>并行抓取十个搜索结果会为你不会读取的页面成倍增加成本和延迟。请先抓取最有可能回答问题的两三个结果，并仅逐步提高并发，直到 <code>429</code> 出现错误为止。</td></tr></tbody></table>

## 专用爬虫

除通用 URL 抓取外，还可以使用面向目标的爬虫配合 `POST /v1/scrape/{target}/{collection}`。它们接受目标特定参数（例如 ASIN、浏览节点、商店邮编），并返回位于其下的结构化字段 `results[].json`:

```bash
curl https://webapi.oxylabs.io/v1/scrape/amazon/product \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{
    "query": "B0935DN1BN",
    "output": ["json"],
    "location": "10115",
    "domain": "de",
    "currency": "EUR"
  }'
```

参见 [专用爬虫](/products/cn/web-api/scrape/zhuan-yong-pa-chong.md) 目标概览（Google、Amazon、YouTube、Bing、AI 和 LLM、Commerce 等）。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-api/scrape.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.