# URL 转 Markdown API 快速入门：两分钟读取第一个页面

> URL 转 Markdown API 快速入门：获取密钥，用 curl、Python 或 Node.js 读取你的第一个页面，并查看你的积分。低至 US$0.07/千页，无需 KYC。

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

一个 endpoint，一个参数：将 URL 发送到 `/read`，即可获取页面正文的 Markdown 内容。本页将带你从零余额到成功调用，并指向其他所有内容。

**快速回答 — 如何用 API 将 URL 转换为 Markdown？**

将 URL 发送到 `GET https://webreaderapi.com/api/v1/read`，并在 `Authorization` 请求头中携带你的 API 密钥。**WebReaderAPI** 会抓取页面，保留正文，并以 Markdown 形式返回，并附带标题、作者、日期和字数。一个页面消耗 1 积分（如需浏览器则消耗 2 积分），截至 2026 年 10 月，价格从 US$0.07/千页 起。无需 KYC；使用加密货币支付。

## API 一览表

| 属性 | 值 |
| --- | --- |
| Base URL | `https://webreaderapi.com/api/v1` |
| 读取单个页面 | `GET` 或 `POST https://webreaderapi.com/api/v1/read` |
| 多个 URL 或整站 | `POST https://webreaderapi.com/api/v1/batch` 和 `POST https://webreaderapi.com/api/v1/crawl`，结果从 `GET https://webreaderapi.com/api/v1/jobs/{job_id}` 开始 |
| 剩余积分 | `GET https://webreaderapi.com/api/v1/credits`（免费） |
| 身份验证 | 在 Authorization 请求头中以 Bearer token 形式发送你的 API 密钥，或在 api_key 查询参数中发送 |
| 计费 | 1 积分 = 读取 1 个页面且无需浏览器；当页面需要浏览器渲染 JavaScript 时为 2 积分。失败的请求，或被网站 robots.txt 拒绝的请求，不扣费 |
| 我们的爬虫 | `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)`，robots.txt 令牌 `WebReaderAPI` |
| 最小积分包 | 10,000 个网页 兑换 US$3.75；积分永不过期 |

## 如何获取 API 密钥？

三步搞定，无需填表。最慢的一步是你的充值在区块链上确认。

1. **用加密货币充值** — 发送至少 US$25 的 BTC, USDT, USDC, ETH, SOL, LTC。使用账号登录；邮箱为可选。
2. **购买积分包** — 10,000 个网页 换 US$3.75 足够在你自己的 URL 上测试每个选项。
3. **复制你的密钥** — 你的加密货币充值确认且购买积分包后，API 密钥即在控制台中可用。将它存进名为 WEBREADER_API_KEY 的环境变量。

## 第一个请求长什么样？

就是一个普通的 HTTPS GET，页面地址放在 `url` 参数里。要对地址进行编码，因为它本身含有 `:` 和 `/` 字符；用 `--data-urlencode` 时 curl 会替你完成编码。默认设置已经适合大多数文章和文档页面：Markdown 输出、只取正文、仅在页面需要时才用浏览器。

*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"
```

*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"},
    timeout=70,
)
resp.raise_for_status()
page = resp.json()
print(page["title"], "-", page["word_count"], "words,", page["credits_used"], "credit(s)")
with open("first-post.md", "w", encoding="utf-8") as f:
    f.write(page["markdown"])

```

*Node.js 18+：读取一个页面*

```javascript
const params = new URLSearchParams({ url: 'https://example.com/blog/first-post' });
const res = await fetch(`https://webreaderapi.com/api/v1/read?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WEBREADER_API_KEY}` },
});
const page = await res.json();
if (!res.ok) throw new Error(`${page.error.code}: ${page.error.message}`);
console.log(page.title, page.word_count, 'words');
console.log(page.markdown.slice(0, 500));

```

## 返回什么？

一个 JSON 对象，Markdown 在 `markdown` 字段中，旁边是页面元数据：`title`、`description`、`author`、`published_at`、`language`、`site_name` 和 `word_count`。有两个字段帮你核实发生了什么：`final_url` 是重定向后的地址，`rendered` 告诉你当时是否需要浏览器。

`credits_used` 显示这次调用的花费：普通页面 1，`rendered` 为 `true` 时 2，若你选择了 `country` 再加 1。[响应格式](https://webreaderapi.com/zh/docs/response/) 页面列出了每个字段并附示例。

## 哪些选项我会用得最多？

五个参数覆盖大多数需求，全部可选。

| 参数 | 用途 |
|---|---|
| `format` | 获取 `text` 或清理后的 `html`，而不是 `markdown` |
| `main_content` | 设置 `false` 以转换整个页面，包括菜单 |
| `render` | 强制（`true`）或禁止（`false`）浏览器；`auto` 决定 |
| `include_links` | 以单独列表获取页面的链接 |
| `max_chars` | 截断长页面以适配模型的上下文预算 |

[读取参考](https://webreaderapi.com/zh/docs/read/) 介绍了每个参数，包括 `country`、`include_images` 和 `timeout`。

## 如何查看剩余积分？

用同一个密钥调用 `GET https://webreaderapi.com/api/v1/credits`。它返回 `credits_remaining`、`credits_used_today` 和你的 `concurrency_limit`，并且不花费任何积分。在长任务开始时运行它，这样任务可以干净地停止，而不是中途因 `402 insufficient_credits` 失败。

预付费积分永不过期：未使用的页面数会一直保留在你的账户中，直到你使用，因此为一个项目购买的积分包在下一个项目中依然保值。

## 如果网站不允许 robots 怎么办？

我们不读取该页面，也不向你收费。我们的爬虫以 `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)` 标识自身，并遵守网站的 robots.txt。被禁止的页面返回 `403 blocked_by_robots`；以其他方式拒绝请求的网站返回 `502 target_refused` 并附带该网站自己的状态码。

如果网站拒绝我们的请求，我们会返回其答复：我们从不破解 CAPTCHA、不登录账户，也不试图绕过封锁或付费墙。[错误页面](https://webreaderapi.com/zh/docs/errors/) 说明了哪些错误值得重试、哪些是最终错误。

## 接下来去哪？

- [阅读 endpoint 参考](https://webreaderapi.com/zh/docs/read/) — /read 的每个参数及示例
- [批量与整站抓取](https://webreaderapi.com/zh/docs/crawl/) — 每批最多 100 个 URL，或整站抓取 (crawl)
- [响应格式](https://webreaderapi.com/zh/docs/response/) — 响应的每个字段
- [错误与 robots.txt](https://webreaderapi.com/zh/docs/errors/) — 状态码、原因和重试规则
- [Python](https://webreaderapi.com/zh/docs/python/) — requests、async httpx、RAG 分块
- [Node.js](https://webreaderapi.com/zh/docs/node/) — fetch、小型连接池、crawl 轮询
- [curl 和 jq](https://webreaderapi.com/zh/docs/curl/) — 终端操作配方
- [MCP server](https://webreaderapi.com/zh/docs/mcp/) — 适用于 Claude 和 Cursor 的 read_url 工具
- [LangChain 和 LlamaIndex](https://webreaderapi.com/zh/docs/langchain/) — 适用于 RAG 的加载器和工具
- [OpenAI function calling](https://webreaderapi.com/zh/docs/openai/) — read_url 工具 schema 和循环
- [n8n](https://webreaderapi.com/zh/docs/n8n/) — 适用于 AI Agent 的 HTTP Request 工具
- [OpenClaw](https://webreaderapi.com/zh/docs/openclaw/) — 在 web_fetch 旁边添加 MCP 服务器

## 快速开始：常见问题

### 有 SDK 需要安装吗？

没有。WebReaderAPI 是普通的 HTTPS API，因此任何 HTTP 客户端都能用。文档提供了 Python、Node.js 和 curl 的复制粘贴代码，以及 MCP、LangChain、LlamaIndex 和 OpenAI function calling 的工具定义。没有任何东西以包的形式发布。

### 可以把密钥放在 URL 里而不是 header 里吗？

可以，作为 `api_key` 查询参数。`Authorization: Bearer` header 更安全，因为 URL 常常会出现在日志和浏览器历史中。创建多个 API 密钥，例如每个 agent 或项目一个，并可从控制台撤销其中任意一个。

### 失败的页面会消耗积分吗？

不会。1 积分 = 读取 1 个页面且无需浏览器；当页面需要浏览器渲染 JavaScript 时为 2 积分。失败的请求，或被网站 robots.txt 拒绝的请求，不扣费。只有返回内容的页面才计费。

### 可以先试用再购买吗？

没有免费套餐。没有免费套餐：最小的积分包是测试的途径，用最低充值额支付，仅为达到该最低额而多充的金额，可在 30 天内按要求以 USDT 或 USDC 退回，前提是尚未使用。

---

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