快速回答
如何用 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 密钥?
三步搞定,无需填表。最慢的一步是你的充值在区块链上确认。
用加密货币充值
发送至少 US$25 的 BTC, USDT, USDC, ETH, SOL, LTC。使用账号登录;邮箱为可选。
购买积分包
10,000 个网页 换 US$3.75 足够在你自己的 URL 上测试每个选项。
复制你的密钥
你的加密货币充值确认且购买积分包后,API 密钥即在控制台中可用。将它存进名为
WEBREADER_API_KEY的环境变量。
第一个请求长什么样?
就是一个普通的 HTTPS GET,页面地址放在 url 参数里。要对地址进行编码,因为它本身含有 : 和 / 字符;用 --data-urlencode 时 curl 会替你完成编码。默认设置已经适合大多数文章和文档页面:Markdown 输出、只取正文、仅在页面需要时才用浏览器。
curl -sG "https://webreaderapi.com/api/v1/read" \
-H "Authorization: Bearer $WEBREADER_API_KEY" \
--data-urlencode "url=https://example.com/blog/first-post"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"])
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。响应格式 页面列出了每个字段并附示例。
哪些选项我会用得最多?
五个参数覆盖大多数需求,全部可选。
| 参数 | 用途 |
|---|---|
format | 获取 text 或清理后的 html,而不是 markdown |
main_content | 设置 false 以转换整个页面,包括菜单 |
render | 强制(true)或禁止(false)浏览器;auto 决定 |
include_links | 以单独列表获取页面的链接 |
max_chars | 截断长页面以适配模型的上下文预算 |
读取参考 介绍了每个参数,包括 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、不登录账户,也不试图绕过封锁或付费墙。错误页面 说明了哪些错误值得重试、哪些是最终错误。
接下来去哪?
- 阅读 endpoint 参考 /read 的每个参数及示例
- 批量与整站抓取 每批最多 100 个 URL,或整站抓取 (crawl)
- 响应格式 响应的每个字段
- 错误与 robots.txt 状态码、原因和重试规则
- Python requests、async httpx、RAG 分块
- Node.js fetch、小型连接池、crawl 轮询
- curl 和 jq 终端操作配方
- MCP server 适用于 Claude 和 Cursor 的 read_url 工具
- LangChain 和 LlamaIndex 适用于 RAG 的加载器和工具
- OpenAI function calling read_url 工具 schema 和循环
- n8n 适用于 AI Agent 的 HTTP Request 工具
- 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 退回,前提是尚未使用。