# 阅读 endpoint 参考文档：GET 和 POST /read

> 阅读 endpoint 参考文档：GET 和 POST /read 的每个参数，从 format、render 到 country 和 max_chars，并附示例。从 US$0.07/千页 起，无需 KYC。

- URL: https://webreaderapi.com/zh/docs/read/
- 最后更新: 2026-10-22
- 发布者: WebReaderAPI (https://webreaderapi.com)

`/read` 抓取一个公开页面，提取其正文，并以 Markdown、纯文本或清理后的 HTML 返回。本页列出每个参数、其默认值以及费用。

**快速回答 — WebReaderAPI 的 read endpoint 接受哪些参数？**

**WebReaderAPI** 的 `/read` endpoint 需要一个参数，`url`。可选参数则决定输出格式（`format`）、保留页面的多少内容（`main_content`）、是否运行浏览器（`render`）、链接与图片、读取所在国家、字符上限和超时。普通页面花费 1 积分，使用浏览器则 2 积分，自 2026 年 10 月起从 US$0.07/千页 起。无需 KYC；可使用加密货币支付。

## /read at a glance

| 属性 | 值 |
| --- | --- |
| 方法 | `GET` 带查询参数，或 `POST` 带 JSON body，使用相同的名称 |
| URL | `https://webreaderapi.com/api/v1/read` |
| 必填 | `url`：一个 http 或 https 地址，最多 2,048 个字符 |
| 默认输出 | 正文的 Markdown |
| 计费 | 1 积分 = 读取 1 个页面且无需浏览器；当页面需要浏览器渲染 JavaScript 时为 2 积分。失败的请求，或被网站 robots.txt 拒绝的请求，不扣费 |
| 国家 | 选择页面的读取国家会额外增加 10 积分，因为此时页面会通过该国家的住宅连接读取 |
| PDF | 最大 20 MB、100 页的 PDF 文件可转换为 Markdown，每 10 页（不足 10 页按 10 页计）1 积分 |
| 爬虫身份 | `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)` |

## 读取一个页面（GET）

`GET /api/v1/read`

抓取一个公开页面，并以 Markdown 返回其正文，同时附带页面 metadata。参数放在查询字符串中，经过 URL 编码。示例读取一篇博客文章；ID、日期和值仅作示例。

认证：将 API 密钥放在 `Authorization: Bearer API_KEY` 请求头中。

**参数**

| 名称 | 位置 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| `url` | query | string | 是 | 要读取的页面：http 或 https，最多 2,048 个字符。私有、本地和云 metadata 地址会被拒绝。 |
| `format` | query | string | 否 | `markdown`（默认）、`text`（纯文本，无标记）或 `html`（内容清理后的 HTML）。 |
| `main_content` | query | boolean | 否 | `true`（默认）只保留文章或正文；`false` 转换整个页面，包括菜单和页脚。 |
| `render` | query | string | 否 | `auto`（默认）只有当原始 HTML 文本太少时才启动浏览器；`true` 总是启动；`false` 从不启动。渲染过的页面花费 2 积分。 |
| `include_links` | query | boolean | 否 | `true` 会添加一个 `links` 列表，包含 `{url, text}`。默认 `false`。 |
| `include_images` | query | boolean | 否 | `true` 在 Markdown 中将图片保留为 `![alt](src)`。默认 `false`。 |
| `country` | query | string | 否 | 两位国家代码（ISO 3166-1 alpha-2）。页面会从该国家的一个地址读取，额外花费 10 积分（住宅连接）。 |
| `max_chars` | query | integer | 否 | 将输出截断到此字符数，从 1,000 到 500,000。适合用来适配模型的上下文。 |
| `timeout` | query | integer | 否 | 等待网站响应的秒数，范围 5 到 60，默认 30。 |
| `api_key` | query | string | 否 | 你的 API 密钥，如果你没有发送 `Authorization` header。 |

**响应** `200`

```json
{
  "url": "https://example.com/blog/first-post",
  "final_url": "https://example.com/blog/first-post",
  "status_code": 200,
  "fetched_at": "2026-10-22T09:41:12Z",
  "rendered": false,
  "credits_used": 1,
  "title": "Our first post",
  "description": "Why we started this blog and what comes next.",
  "language": "en",
  "author": "Jane Doe",
  "published_at": "2026-10-01",
  "site_name": "Example Blog",
  "markdown": "# Our first post\n\nWe started this blog to share what we learn...\n\n## What comes next\n\n- A post every month\n- Notes from our team",
  "word_count": 612
}
```

*curl*

```bash
curl -sG "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/blog/first-post" \
  -d format=markdown -d max_chars=20000
```

*Python*

```python
import os
import requests

resp = requests.get(
    "https://webreaderapi.com/api/v1/read",
    headers={"Authorization": "Bearer " + os.environ["WEBREADER_API_KEY"]},
    params={"url": "https://example.com/blog/first-post", "max_chars": 20000},
    timeout=70,
)
resp.raise_for_status()
print(resp.json()["markdown"][:300])
```

*Node.js*

```javascript
const params = new URLSearchParams({ url: 'https://example.com/blog/first-post', max_chars: '20000' });
const res = await fetch(`https://webreaderapi.com/api/v1/read?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WEBREADER_API_KEY}` },
});
const page = await res.json();
console.log(page.markdown.slice(0, 300));
```

## 读取单个页面（POST）

`POST /api/v1/read`

同一个 endpoint，同样的参数，以 JSON body 发送。当 URL 非常长，或者你的 HTTP 客户端构建 JSON 比构建查询字符串更容易时，优先使用 POST。响应与 GET 形式完全一致。

认证：将 API 密钥放在 `Authorization: Bearer API_KEY` 请求头中。

**请求体**

| 字段 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `url` | string | 是 | 要读取的页面。 |
| `format`, `main_content`, `render`, `include_links`, `include_images`, `country`, `max_chars`, `timeout` | mixed | 否 | 与上面 GET 表格中的相同，使用 JSON 类型：布尔值为 `true`/`false`，数字不加引号。 |

*示例: a JavaScript-heavy page, read from Germany, with its links*

```json
{
  "url": "https://example.com/app/pricing",
  "render": "true",
  "country": "de",
  "include_links": true,
  "max_chars": 30000
}
```

**响应** `200`

```json
{
  "url": "https://example.com/app/pricing",
  "final_url": "https://example.com/de/app/pricing",
  "status_code": 200,
  "fetched_at": "2026-10-22T09:44:03Z",
  "rendered": true,
  "credits_used": 3,
  "title": "Pricing",
  "language": "de",
  "markdown": "# Pricing\n\n| Plan | Price |\n|---|---|\n| Basic | ... |",
  "word_count": 214,
  "links": [
    {
      "url": "https://example.com/de/contact",
      "text": "Contact"
    }
  ]
}
```

*curl*

```bash
curl -s "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/app/pricing", "render": "true", "country": "de", "include_links": true}'
```

*Python*

```python
import os
import requests

resp = requests.post(
    "https://webreaderapi.com/api/v1/read",
    headers={"Authorization": "Bearer " + os.environ["WEBREADER_API_KEY"]},
    json={"url": "https://example.com/app/pricing", "render": "true", "country": "de", "include_links": True},
    timeout=70,
)
print(resp.json()["credits_used"], "credits")
```

*Node.js*

```javascript
const res = await fetch('https://webreaderapi.com/api/v1/read', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBREADER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/app/pricing', render: 'true', country: 'de', include_links: true }),
});
console.log((await res.json()).credits_used);
```

## 我应该选择哪种输出格式？

为语言模型和 RAG 选择 `markdown`：标题、列表、表格和链接都会保留，文本保持紧凑。如果你只统计词数、分类或搜索，标记只会是噪音，就选择 `text`。如果你自己的 pipeline 已经解析 HTML，只想去掉杂乱内容，就选择 `html`。

三种格式的 metadata 字段都相同，只有内容字段的名称不同：`markdown`、`text` 或 `html`。

## 什么时候应该把 main_content 设为 false？

当你需要的是文章周围的部分时，把它设为 `false`。例如用网站导航来梳理其版块、含法律或联系信息的页脚，或者规格参数位于侧边栏的产品页。

在默认值 `true` 下，提取器会保留主内容块，去掉导航、cookie 横幅、广告、分享按钮和页脚。这正是大多数 agent 和 RAG pipeline 想要的，而且通常能把页面缩减到其 HTML 体积的一小部分。

## render=auto 如何决定是否使用浏览器？

它先抓取原始 HTML，速度快，消耗 1 积分。如果该 HTML 中可读文本太少（通常是使用 JavaScript 构建页面的应用），它会在无头浏览器中重新加载页面，该次调用消耗 2 积分。响应会告诉你走了哪条路径：`rendered` 为 `true` 或 `false`。

当你知道网站提供完整 HTML 并且想要固定成本时，设置 `render=false`。对于单页应用，设置 `render=true` 以跳过第一次尝试。

## country 和 max_chars 会改变什么？

`country` 会从你指定国家的地址读取页面，User-Agent 相同。适用于价格、语言或可用性随国家而变的页面。它额外增加 10 积分，因为此时页面是通过住宅连接读取的，并且不能用于该服务不运营的国家。

`max_chars` 会在达到该字符数后截断输出。它不改变价格，但能保护 agent 的上下文窗口：对于传给模型的单个页面，20,000 个字符是一个合理的默认值。

## /read 能处理 PDF 文件吗？

可以。当 URL 返回 PDF 时，文本会以 Markdown 的形式通过同一个 `markdown` 字段返回。最大 20 MB、100 页的 PDF 文件可转换为 Markdown，每 10 页（不足 10 页按 10 页计）1 积分。没有文本层的扫描版 PDF 返回的文本很少或没有，因为没有字符识别步骤。

## 读取 endpoint：常见问题

### /read 会跟随重定向吗？

会，最多 5 次。响应会在 `url` 中给出你请求的地址，在 `final_url` 中给出实际读取的地址。重定向到私有或本地地址会被拒绝。

### 我可以读取需要登录的页面吗？

不可以。如果网站拒绝我们的请求，我们会返回其答复：我们从不破解 CAPTCHA、不登录账户，也不试图绕过封锁或付费墙。位于登录或付费墙之后的页面会返回网站的拒绝结果，并且该次调用免费。

### 每次调用都会检查 robots.txt 吗？

会，对照网站 robots.txt 的副本进行，该副本最多 24 小时。被禁止的 URL 会返回 `403 blocked_by_robots`，且不消耗积分。

### 我可以同时读取多少个页面？

每个账户都有同时读取页面数的上限；你的控制台会显示该上限，支持团队可将其提高。对于大量 URL，[批处理任务](https://webreaderapi.com/zh/docs/crawl/) 比运行许多并行调用更简单。

---

WebReaderAPI: WebReaderAPI 是一款面向 AI agents 的网页读取 API，可将任何公开网页转换为干净的 Markdown，用加密货币支付，无需上传身份证件。预付费积分低至 US$0.07/千页，永不过期，且遵守 robots.txt。无需 KYC — 无身份证、无自拍、无证件。加密货币支付。