# 用 curl 和 jq 将网页转为 Markdown

> 在终端中用 curl 和 jq 把网页转成 Markdown：保存页面、列出其链接、运行批处理并查看积分。从 US$0.07/千页 起步，无需 KYC。

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

API 能做的一切都能装进一行 shell 命令。这些示例用 curl 调用 API、用 jq 从 JSON 中取出字段，末尾附有适用于 Windows 的 PowerShell 版本。

**快速回答 — 如何从命令行将网页转为 Markdown？**

在 `Authorization: Bearer` 请求头中带上你的密钥运行 `curl -sG https://webreaderapi.com/api/v1/read --data-urlencode "url=…"`，然后将结果通过管道传给 `jq -r .markdown`。**WebReaderAPI** 会以 Markdown 返回页面的正文及其元数据。一个普通页面消耗 1 积分，截至 2026 年 10 月从 US$0.07/千页 起。无需 KYC；使用加密货币支付。

## 如何设置终端？

安装 curl 和 jq（大多数 Linux 和 macOS 系统已自带），并在每个会话中导出一次你的密钥。下面的每个示例都从 `$WEBREADER_API_KEY` 读取密钥，因此密钥不会作为命令的一部分出现在你的 shell 历史记录中。

GET 请求请使用 `-G` 搭配 `--data-urlencode`：这样 curl 会替你编码页面地址，这一点很重要，因为地址本身含有 `?`、`&` 和 `=`。

*设置密钥并将一个页面保存为 .md 文件*

```bash
export WEBREADER_API_KEY="your-key"

curl -sG "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/guides/compost" \
  | jq -r '.markdown' > compost.md
```

## 如何查看一次调用返回了什么、花费了多少？

用 jq 只取 metadata，而不是正文。`final_url` 显示重定向最终指向哪里，`rendered` 告诉你是否使用了浏览器，`credits_used` 是这次调用的费用。如果返回的是错误，同一个过滤器会打印 `null` 字段；打印 `.error` 可读取错误码和消息。

*只打印 metadata，若出错则打印错误*

```bash
curl -sG "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/guides/compost" \
  | jq '.error // {title, final_url, rendered, credits_used, word_count}'
```

## 如何列出页面上的链接？

加上 `include_links=true`，把 `links` 列表转换为制表符分隔的行。这样你就能快速得到页面外链的概览，可以排序、用 grep 过滤，或交给批处理任务。

*链接以文本和 URL 输出，每行一个*

```bash
curl -sG "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/docs/" \
  -d include_links=true \
  | jq -r '.links[] | "\(.text)\t\(.url)"' | sort -u
```

## 如何读取 JavaScript 页面或 PDF？

对于用 JavaScript 构建内容的页面，加上 `-d render=true`；此时消耗 2 积分。PDF 不需要特殊处理：发送其 URL，文本就会在 `markdown` 中返回。最大 20 MB、100 页的 PDF 文件可转换为 Markdown，每 10 页（不足 10 页按 10 页计）1 积分。

*先渲染页面，再读 PDF*

```bash
curl -sG "https://webreaderapi.com/api/v1/read" -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/app/changelog" -d render=true \
  | jq -r '.markdown' > changelog.md

curl -sG "https://webreaderapi.com/api/v1/read" -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/files/annual-report.pdf" \
  | jq -r '.markdown' > annual-report.md
```

## 如何从 shell 运行批处理任务？

向 `/batch` 发送包含 URL 的 JSON 请求体，保存 `job_id`，然后读取任务。一个小循环会等到任务变为 `done`，并打印每个页面的标题或错误码。对于耗时较长的任务，按 [批处理和整站抓取 (crawl) 页面](https://webreaderapi.com/zh/docs/crawl/) 所示的方式跟踪 `next_cursor`。

*三个 URL 的批处理，然后等待结果*

```bash
JOB=$(curl -s "https://webreaderapi.com/api/v1/batch" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/a", "https://example.com/b", "https://example.com/c"]}' \
  | jq -r '.job_id')

until [ "$(curl -s "https://webreaderapi.com/api/v1/jobs/$JOB" -H "Authorization: Bearer $WEBREADER_API_KEY" | jq -r '.status')" = "done" ]; do
  sleep 5
done

curl -s "https://webreaderapi.com/api/v1/jobs/$JOB" -H "Authorization: Bearer $WEBREADER_API_KEY" \
  | jq -r '.results[] | "\(.url)\t\(.title // .error.code)"'
```

## 如何查看我的积分？

调用 `/credits`；此调用免费。它会返回 `credits_remaining`、`credits_used_today` 和你的 `concurrency_limit`。预付费积分永不过期：未使用的页面数会一直保留在你的账户中，直到你使用。

*剩余积分*

```bash
curl -s "https://webreaderapi.com/api/v1/credits" -H "Authorization: Bearer $WEBREADER_API_KEY" | jq '.credits_remaining'
```

## Windows 上的 PowerShell 版本是怎样的？

`Invoke-RestMethod` 会替你解析 JSON，因此不需要 jq。用 `[uri]::EscapeDataString` 构建查询以编码页面地址，并在 headers 表中传入密钥。

*PowerShell：保存一个页面*

```powershell
$headers = @{ Authorization = "Bearer $env:WEBREADER_API_KEY" }
$target = [uri]::EscapeDataString('https://example.com/guides/compost')
$page = Invoke-RestMethod -Uri "https://webreaderapi.com/api/v1/read?url=$target" -Headers $headers
$page.markdown | Out-File -Encoding utf8 compost.md
"$($page.title): $($page.word_count) words, $($page.credits_used) credit(s)"
```

## curl：常见问题

### 为什么我的 URL 中含有 & 时会失败？

因为 shell 或 curl 把它拆开了。将整个 `url=…` 参数用引号括起来，并用 `--data-urlencode` 传入，如上面的示例所示；这样 curl 就会编码页面地址中的 `&`、`?` 和 `=`。

### 如何查看错误的 HTTP 状态？

加上 `-w '\n%{http_code}\n'` 可在正文之后打印它，或加上 `-i` 查看所有 headers。正文中的 `error.code` 是脚本中用于判断的稳定值。

### 失败的调用会计费吗？

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

---

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