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

# 网页转 Markdown API（WEB_SCRAPE）

> 读取一个网页或 PDF，以 Markdown 获取其正文，以及标题、元数据和图片。

`WEB_SCRAPE` 读取一个页面，以 Markdown 返回其正文：标题、段落、列表、表格、链接和图片，并去掉网站的页眉、页脚和导航。商品详情页这类由脚本绘制的页面会先渲染再读取。如需读取搜索结果，请传入 [`GOOGLE_SERP`](/zh/engines/google-serp) 的 `organicResults` 中的 `link`。

| | |
| - | - |
| `taskType` | `WEB_SCRAPE` |
| 输入 | `url`（必填）；`maxChars`、`country` |
| 积分 | 每个任务 1 积分，多页 PDF 也是如此 |
| 国家 | 未发送时为 `US`；Coupang 和 Olive Young 商城页面为 `KR`。 |
| 位置 | 不支持（`422 LOCATION_UNSUPPORTED`）。 |

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "WEB_SCRAPE", "payload": { "url": "https://www.example.com/guide", "maxChars": 50000 } }'
```

任务异步执行。按[异步任务](/zh/concepts/async-tasks.md)中的说明读取结果。

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `url` | 是 | 使用默认端口的公开 `http` 或 `https` 地址，最长 2,048 个字符。包含凭据、指向私有或内部主机或使用其他端口的地址返回 `422 VALIDATION_ERROR`。 |
| `maxChars` | 否 | `markdown` 的上限，1,000 到 200,000 的整数，默认 100,000。 |
| `country` | 否 | 请求页面时使用的语言和地区。省略时，韩国本土 Coupang 和 Olive Young 商城页面使用 `KR`，其他页面使用 `US`。 |

## 响应

例如：

```json theme={"theme":"css-variables"}
{
  "url": "https://www.example.com/guide",
  "finalUrl": "https://www.example.com/guide",
  "statusCode": 200,
  "title": "...",
  "description": "...",
  "author": "...",
  "publishedAt": "2026-09-12T07:36:36Z",
  "siteName": "...",
  "language": "en",
  "image": "https://...",
  "markdown": "# ...\n\n...\n\n![...](https://...)",
  "images": [{ "url": "https://...", "alt": "..." }],
  "truncated": false
}
```

| 字段 | 说明 |
| - | - |
| `url` | 你发送的地址。 |
| `finalUrl` | 跟随重定向后的地址。 |
| `statusCode` | 所读取页面的 HTTP 状态码。 |
| `markdown` | 正文。已完成任务中绝不为空。 |
| `images` | `markdown` 中的图片，按出现顺序排列。 |
| `truncated` | `markdown` 在 `maxChars` 处截止时为 `true`。尽可能在段落边界截断。 |
| `title`、`description`、`author`、`publishedAt`、`siteName`、`language`、`image` | 页面声明时返回。 |

## PDF

支持 HTML、纯文本和含文本的 PDF。PDF 按页序返回文本，并在存在时返回标题、作者、主题（作为 `description`）和语言，`images: []`。不支持 OCR、附件提取和版式重建。

| PDF 限制 | 值 |
| - | - |
| 下载大小 | 8 MiB |
| 页数 | 100 |
| 提取文本 | 1,000,000 个字符 |
| 提取时间 | 20 秒 |

无论 `maxChars` 如何设置，都会检查整个文档；只截短返回的 Markdown。无文本、加密、损坏、不完整或超限的 PDF 均以 `PAGE_UNAVAILABLE` 失败。

## 限制与错误

* 无法读取的页面会使任务以 `PAGE_UNAVAILABLE` 失败并附带原因：不支持的格式、返回 404 或 410 的页面，或拒绝请求的网站。
* 重定向到违反 `url` 规则的地址会使任务失败。每一跳重定向都会再次检查这些规则。
* `WEB_SCRAPE` 忽略 `markdown`、`rawResponse` 和 `searchQueries`。它以 `422` 拒绝 `html` 和 `analysis`，以 `400` 拒绝 `citationAnalysis`；见[不支持的标志](/zh/engines/response-options.md#不支持的标志)。
* 其他请求错误见[错误](/zh/concepts/errors.md)。

## 相关内容

* [网站爬取](/zh/engines/web-crawl.md)：读取同一站点的多个页面
* [网站地图](/zh/engines/web-map.md)：先列出站点的地址


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.