# 网页搜索 API 的 curl 和 jq 用法示例

> 用 curl 和 jq 调用网页搜索 API：搜索、列出来源、将网页保存为 Markdown、按新闻和域名筛选、读取已知 URL、查询积分。无需 KYC，加密货币支付。

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

API 的每项功能都能在终端里使用。这些示例用 `curl` 调用它，用 `jq` 处理 JSON：适合在写代码前测试查询、编写 shell 脚本以及运行 cron 任务。

**快速回答 — 如何从命令行使用网页搜索 API？**

向 `https://llmwebsearch.com/api/v1/search` 发送包含 `curl -d` 的 JSON 请求体，在 `Authorization: Bearer` 请求头中带上你的密钥，再把响应通过管道传给 `jq`。**LLMWebSearch** 返回带排名的结果，并将前 3 个网页以 Markdown 形式返回，因此一行命令就能列出来源或把网页保存为文件。一次搜索消耗 1 积分，截至 2026 年 10 月低至 US$1.20/千次搜索。无需 KYC；加密货币支付。

## 如何一次性设置好终端？

在 shell 中导出你的密钥，这样它就不会出现在你输入的命令里，也不会留在历史记录中。下面的示例通过 `$LLMWEBSEARCH_API_KEY` 读取它。你还需要 `jq`，大多数包管理器都以该名称安装它。

所有示例都假定使用 bash 或 zsh 等 POSIX shell。在 Windows 上，Git Bash 或 WSL 可原样运行它们。

*设置密钥并查询余额（免费）*

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

curl -s "https://llmwebsearch.com/api/v1/credits" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" | jq .
```

## 如何列出一次搜索的来源？

将 `read` 设为 `0` 运行搜索，并为每条结果打印一行：位置、主机和 URL。这消耗 1 积分，能让你在一秒内看到一个问题会带出哪些来源。在让 AI agent 使用某个查询之前，这是调整其措辞的好方法。

*每条结果一行*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "max_results": 10, "read": 0}' \
  | jq -r '.results[] | "\(.position)\t\(.host)\t\(.url)"'
```

## 如何保存已读取的网页？

保留 `content_status` 为 `ok` 的结果，并将每个 `content` 写入单独的文件。下面的示例会保存 `01.md`、`02.md` 等，每个文件以其来源 URL 开头。jq 负责筛选结果，shell 循环负责写入文件。

*将每个网页保存为 Markdown*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "read": 3}' > search.json

jq -r '.results[] | select(.content_status == "ok") | .position' search.json | while read -r pos; do
  jq -r --argjson p "$pos" '.results[] | select(.position == $p) | "Source: " + .url + "\n\n" + .content' \
    search.json > "$(printf '%02d' "$pos").md"
done
ls -1 ./*.md
```

## 如何从几个网站搜索新闻？

向请求体添加 `topic`、`time_range` 和 `include_domains`。该示例保留两个域名上过去一周的新闻，并在每个标题旁打印日期，这足以通过 cron 任务关注某个主题。

*两个域名过去一周的新闻*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database security release", "topic": "news", "time_range": "week", "include_domains": ["news.example.com", "example.org"], "read": 0}' \
  | jq -r '.results[] | "\(.published_at // "no date")  \(.title)  \(.url)"'
```

## 如何使用 GET 形式？

使用 `curl -G` 配合 `--data-urlencode` 传入查询，这样空格和符号会自动编码。像 `include_domains` 这样的列表会变成一个逗号分隔的值。GET 便于快速测试；随着脚本变复杂，应改用 POST。

*GET /search*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=pgbouncer transaction mode" \
  -d read=1 -d max_chars=3000 -d include_domains=example.com,example.org \
  | jq -r '.results[0].content // .results[0].snippet'
```

## 如何读取已有的 URL？

以包含 1 到 20 个地址的 JSON 数组形式将它们 POST 到 `/extract`。读取你已持有 URL 的页面：每开始一组 3 个返回内容的页面计 1 积分，每次调用最多 20 个 URL；被拒绝或失败的 URL 不计入。该示例打印每个 URL 及其状态和字数，让你一眼看出网站允许我们读取了哪些网页。

*POST /extract*

```bash
curl -s "https://llmwebsearch.com/api/v1/extract" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://docs.example.com/security/key-rotation", "https://example.com/changelog"]}' \
  | jq -r '"credits: \(.credits_used)", (.results[] | "\(.content_status)\t\(.word_count // 0)\t\(.url)")'
```

## 调用失败时如何查看错误？

用 `-w` 打印 HTTP 状态码并保留响应体：错误会以 JSON 返回，包含 `code` 和 `message`。脚本可据此根据状态码分支处理，例如仅在 `429`、`502` 或 `504` 时等待并重试。这些错误都不消耗积分。

*状态码与错误响应体*

```bash
status=$(curl -s -o body.json -w '%{http_code}' "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "test query"}')
if [ "$status" != "200" ]; then
  echo "HTTP $status: $(jq -r '.error.code + " - " + .error.message' body.json)"
fi
```

## curl：常见问题

### 为什么我的 JSON 请求体返回 invalid_parameter？

通常是引号问题。在 bash 中用单引号包裹请求体，让里面的双引号保持原样，并在发送前用 `echo '…' | jq .` 检查。

### 可以在 URL 中传递密钥吗？

可以，用 GET 形式加 `-d api_key=…`。使用请求头更安全，因为 shell 历史和代理日志会记录 URL。

### curl 调用失败会消耗积分吗？

不会。HTTP 错误从不消耗积分。只有返回结果的搜索才会计费，如 `credits_used` 所示。

---

LLMWebSearch: LLMWebSearch 是一款面向 AI 智能体的网页搜索 API，返回排序后的搜索结果，并附带热门页面的 Markdown 格式内容，采用加密货币支付，无需上传证件。预付费积分低至 US$1.20/千次搜索，永不过期。无 KYC——无需证件、无需自拍、无需提交任何文件。加密货币支付。