# Web 搜索 API 快速开始：两分钟内完成你的第一次搜索

> Web 搜索 API 快速开始：获取密钥，用 curl、Python 或 Node.js 运行你的第一次搜索，并将头部页面以 Markdown 读取。无需 KYC，用加密货币支付。

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

一个端点完成全部工作：向 `/search` 发送问题，取回排序后的结果，其中头部页面已被读取并清理为 Markdown。本页从空余额讲到成功调用，然后指向文档的其他每一页。

**快速回答 — 如何用面向 AI agent 的 Web 搜索 API 运行我的第一次搜索？**

将你的问题发送到 `POST https://llmwebsearch.com/api/v1/search`，并把 API 密钥作为 Bearer token。**LLMWebSearch** 会运行实时 Web 搜索并返回最多 20 条排序结果，其中前 3 个页面会被读取并以 Markdown 返回。一次调用消耗 1 积分，自 2026 年 10 月起 US$1.20/千次搜索 起。无需 KYC；用加密货币支付。

## 一张卡片了解 API

| 属性 | 值 |
| --- | --- |
| Base URL | `https://llmwebsearch.com/api/v1` |
| 搜索 | `POST` 或 `GET https://llmwebsearch.com/api/v1/search` |
| 读取你已有的 URL | `POST https://llmwebsearch.com/api/v1/extract` |
| 剩余积分 | `GET https://llmwebsearch.com/api/v1/credits`，免费 |
| 身份验证 | 将 API 密钥作为 Bearer token 放在 Authorization 请求头中传入，或作为 api_key 查询参数传入 |
| 计费 | 1 积分支付一次查询：最多 20 条排名结果，其中前 3 条的页面会被读取并以 Markdown 返回。读取 4 到 10 个页面为 2 积分。以错误结束的调用不收费 |
| 我们的网页读取器 | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)`，robots.txt token `LLMWebSearch` |
| 最小积分包 | 5,000 次搜索 兑换 US$9.25；积分永不过期 |

## 如何获取 API 密钥？

没有注册表单。等待区块链确认你的充值是最耗时的环节。

1. **用加密货币充值余额** — 至少发送 US$25（BTC, USDT, USDC, ETH, SOL, LTC）。用账号编号登录；电子邮箱地址为选填。
2. **购买搜索积分包** — 5,000 次搜索 兑换 US$9.25 足够你把搜索接入一个 agent 并试遍所有选项。
3. **复制密钥** — 你的加密货币充值一经确认并购买了积分包，API 密钥就在控制面板中等着你。把它保存在名为 LLMWEBSEARCH_API_KEY 的环境变量中。

## 第一次搜索是什么样的？

它就是一个 HTTPS POST，请求体是一小段 JSON。只有 `q` 是必填的：问题或关键词，按人们平常输入的方式写即可。默认值已经适合大多数 agent。你会得到 5 条排序结果，前 3 条结果对应的页面会被读取，并以 Markdown 形式返回，每页最多 6,000 个字符。

下面三段代码发送的是同一个搜索。挑一个与你的技术栈匹配的，在 shell 中设置 `LLMWEBSEARCH_API_KEY`，然后运行它。

*curl：一次搜索，读取前 3 个页面*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3}'
```

*Python：列出来源及其大小*

```python
import os

import requests

resp = requests.post(
    "https://llmwebsearch.com/api/v1/search",
    headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]},
    json={"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3},
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print("credits used:", data["credits_used"])
for r in data["results"]:
    size = r.get("word_count", 0)
    print(r["position"], r["title"], r["url"], r["content_status"], size, "words")

```

*Node.js 18+：打印第一个被读取的页面*

```javascript
const res = await fetch('https://llmwebsearch.com/api/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ q: 'how to rotate api keys without downtime', max_results: 5, read: 3 }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const first = data.results.find((r) => r.content_status === 'ok');
console.log(first ? `${first.title}\n${first.url}\n\n${first.content.slice(0, 600)}` : 'No page could be read.');

```

## 返回什么？

一个 JSON 对象，包含你的 `query`、调用时间（`created_at`）、价格（`credits_used`），以及按排序排列的 `results` 数组。每条结果都有其 `position`、`title`、`url`、`host` 和 `snippet`，日期已知时还会有 `published_at`。

需要关注的字段是 `content_status`。当它显示 `ok` 时，页面已被读取，正文位于 `content`，并带有 `word_count`。超出 `read` 的结果显示 `not_requested`。无法读取的页面会说明原因，例如 `blocked_by_robots`。[响应格式](https://llmwebsearch.com/zh/docs/response/)页面解释了每个字段。

## 我最常改动哪些参数？

六个参数几乎覆盖所有 agent。它们全部是可选的。

| 参数 | 改变什么 |
|---|---|
| `max_results` | 返回多少条排序结果，1 到 20 |
| `read` | 读取前多少条结果，0 到 10 |
| `max_chars` | 每个页面内容的长度上限，500 到 50,000 个字符 |
| `topic` 和 `time_range` | 用新闻代替网页，以及时效窗口 |
| `include_domains` | 只返回你列出的网站的结果 |
| `country` 和 `language` | 搜索在何处、以何种语言运行 |

[搜索参考](https://llmwebsearch.com/zh/docs/search/)为每个参数配有示例，还包括 `format` 和 `exclude_domains`。

## 一次调用消耗多少积分？

大多数调用消耗 1 个积分。完整规则如下：

- **搜索读取 0 到 3 个页面：1 积分。** 包含最多 20 条排序结果。
- **搜索读取 4 到 10 个页面：2 积分。**
- **网页转 Markdown：** 读取你已持有 URL 的页面：每开始一组 3 个返回内容的页面计 1 积分，每次调用最多 20 个 URL；被拒绝或失败的 URL 不计入。
- **错误：0 积分。** 参数错误、密钥错误、余额为空或搜索失败都不收费。
- **成功搜索中无法读取的页面**不影响其价格。
- **用 `GET https://llmwebsearch.com/api/v1/credits` 查看余额**是免费的。

查询积分永不过期：这个月没用完的，明年还在。

## 网站不希望被读取时会发生什么？

结果仍会出现，带有标题、URL 和摘要，但不含页面内容。我们的读取器遵守 robots.txt：它会以 LLMWebSearch 表明身份，遵守网站为它或为所有机器人写下的规则，并排除任何它无权读取的页面内容。在 robots.txt 中设置 Content-Signal: ai-input=no 的网站，其页面内容不会出现在你的结果中。

当网站对我们的读取器给出拒绝响应时，结果会带有 `content_status: "target_refused"` 以及网站自身的 HTTP 状态码（`target_status`）。当网站拒绝我们的读取器时，结果会不带内容返回，并附上该网站的状态：我们绝不破解 CAPTCHA、不登录账户，也不绕过封锁或付费墙。[错误页面](https://llmwebsearch.com/zh/docs/errors/)列出了所有状态码以及哪些值得重试。

## 接下来去哪里？

- [搜索 endpoint](https://llmwebsearch.com/zh/docs/search/) — /search 的每个参数，附示例
- [提取 endpoint](https://llmwebsearch.com/zh/docs/extract/) — 读取你已有的 1 到 20 个 URL
- [响应格式](https://llmwebsearch.com/zh/docs/response/) — 每个字段及所有 content_status
- [错误](https://llmwebsearch.com/zh/docs/errors/) — HTTP 错误、页面状态、重试规则
- [Python](https://llmwebsearch.com/zh/docs/python/) — requests、async httpx、带引用的回答
- [Node.js](https://llmwebsearch.com/zh/docs/node/) — fetch、一个小连接池、同样的引用循环
- [curl 和 jq](https://llmwebsearch.com/zh/docs/curl/) — 终端食谱
- [MCP server](https://llmwebsearch.com/zh/docs/mcp/) — 适用于 Claude Code 和 Claude Desktop 的 search_web
- [LangChain 和 LlamaIndex](https://llmwebsearch.com/zh/docs/langchain/) — 工具与检索器
- [OpenAI function calling](https://llmwebsearch.com/zh/docs/openai/) — 工具 schema、循环与 Agents SDK
- [n8n](https://llmwebsearch.com/zh/docs/n8n/) — 用于 AI Agent 的 HTTP Request 工具
- [OpenClaw](https://llmwebsearch.com/zh/docs/openclaw/) — 通过 MCP 使用我们的搜索

## 快速开始：常见问题

### 我需要 SDK 吗？

不需要。LLMWebSearch 是一个普通的 HTTPS API，所以任何 HTTP 客户端都能用。这些文档提供了 Python、Node.js 和 curl 的可复制粘贴代码，以及 MCP、LangChain、LlamaIndex、OpenAI function calling、n8n 和 OpenClaw 的工具定义。我们不发布任何包。

### API 会替我把答案写好吗？

不会。API 返回的是来源，而不是写好的答案：由你自己的模型读取页面、撰写回复并引用 URL。这样可以让你自由选择模型、提示词和引用格式。

### 我可以把密钥放在 URL 里吗？

可以，作为 `GET /search` 的 `api_key` 查询参数。`Authorization` 请求头是更安全的选择，因为 URL 会出现在日志和 shell 历史记录中。为每个 agent、应用或团队成员各建一个 API 密钥，并可在控制面板中吊销其中任意一个，而不影响其他密钥。

### 有免费额度可以试用吗？

没有。没有免费套餐：5,000 次查询积分包是试用方式，用最低充值金额即可购买；仅为达到该最低金额而多充的部分，可在 30 天内按要求以 USDT 或 USDC 退回，前提是尚未使用。

---

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