# 搜索接口参考：POST 和 GET /search

> 搜索接口参考：POST 和 GET /search 的所有参数，从 read 和 max_chars 到 topic、time_range 和域名过滤。无需 KYC，加密货币支付。

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

`/search` 会执行实时网页搜索，对最多 20 条结果排序，并读取排在前面的页面。本页列出了所有参数、默认值、限制及其对价格的影响。

**快速回答 — LLMWebSearch 搜索接口接受哪些参数？**

**LLMWebSearch** 的 `/search` 接口只需要 `q`。可选参数用于设置返回结果数量（`max_results`）、读取页面数量（`read`）、内容格式和长度、新闻或网页、时间范围、国家和语言，以及要保留或排除的域名。读取最多 3 个页面花费 1 积分，截至 2026 年 10 月低至 US$1.20/千次搜索。无需 KYC；加密货币支付。

## /search at a glance

| 属性 | 值 |
| --- | --- |
| 方法 | `POST` 使用 JSON 请求体，或 `GET` 将相同名称放在查询字符串中 |
| URL | `https://llmwebsearch.com/api/v1/search` |
| 是否必需 | `q`：1 到 400 个字符；搜索运算符按原文传递 |
| 默认值 | 5 条结果，读取前 3 条，Markdown 每页最多 6,000 个字符 |
| 计费 | 1 积分支付一次查询：最多 20 条排名结果，其中前 3 条的页面会被读取并以 Markdown 返回。读取 4 到 10 个页面为 2 积分。以错误结束的调用不收费 |
| 结果 | 结果来自你调用当下执行的实时网页搜索，按搜索引擎的排名顺序返回；不提供任何来自旧索引的内容 |
| 筛选 | 可选择结果的国家和语言、时间范围（过去一天、一周、一个月或一年）、网页或新闻结果，以及要包含或排除的域名 |
| 网页阅读器 | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)` |

## 搜索网页并读取排名靠前的结果（POST）

`POST /api/v1/search`

执行实时网页搜索并返回排序后的结果。前 `read` 条结果的页面会并行抓取，其正文内容在 `content` 中返回。示例查询的是如何轮换 API 密钥；标题、日期和数值仅为示例。

认证：API 密钥放在 `Authorization: Bearer API_KEY` 请求头中。

**请求体**

| 字段 | 类型 | 是否必需 | 描述 |
| --- | --- | --- | --- |
| `q` | string | 是 | 搜索查询，1 到 400 个字符。引号和 `site:` 等运算符按原文保留。 |
| `max_results` | integer | 否 | 排序结果的数量，1 到 20。默认 5。 |
| `read` | integer | 否 | 读取并随内容返回前几条结果，0 到 10。默认 3。从 4 起，每次调用花费 2 积分。 |
| `format` | string | 否 | 页面内容为 `markdown`（默认）或 `text`。 |
| `max_chars` | integer | 否 | 每个页面内容的长度上限，500 到 50,000 个字符。默认 6,000。 |
| `topic` | string | 否 | `web`（默认）或 `news`。 |
| `time_range` | string | 否 | `day`、`week`、`month` 或 `year`。无默认值：任意日期。 |
| `country` | string | 否 | 搜索运行所在位置的两字母国家代码（ISO 3166-1 alpha-2）。默认 `us`。 |
| `language` | string | 否 | 结果语言，例如 `en`、`de` 或 `pt-BR`。默认 `en`。 |
| `include_domains` | string[] | 否 | 最多 20 个域名；仅保留来自这些域名及其子域名的结果。 |
| `exclude_domains` | string[] | 否 | 最多 20 个域名，其结果的将被排除。 |

*示例: five results, the top three read as Markdown*

```json
{
  "q": "how to rotate api keys without downtime",
  "max_results": 5,
  "read": 3,
  "max_chars": 6000
}
```

*示例: news of the past week from two sites, nothing read*

```json
{
  "q": "open source license change",
  "topic": "news",
  "time_range": "week",
  "include_domains": [
    "news.example.com",
    "example.org"
  ],
  "read": 0
}
```

**响应** `200`

```json
{
  "query": "how to rotate api keys without downtime",
  "created_at": "2026-10-22T10:15:04Z",
  "credits_used": 1,
  "results": [
    {
      "position": 1,
      "title": "Rotating API keys",
      "url": "https://docs.example.com/security/key-rotation",
      "host": "docs.example.com",
      "snippet": "Create a second key, deploy it everywhere, then revoke the first one.",
      "published_at": "2026-09-30",
      "content_status": "ok",
      "content": "# Rotating API keys\n\n## Zero-downtime rotation\n\n1. Create a second key.\n2. Deploy it to every service.\n3. Revoke the old key.",
      "word_count": 948
    },
    {
      "position": 2,
      "title": "Key rotation checklist",
      "url": "https://blog.example.org/key-rotation-checklist",
      "host": "blog.example.org",
      "snippet": "Keep two keys active during the switch and alert on the old one.",
      "content_status": "blocked_by_robots"
    },
    {
      "position": 3,
      "title": "Secrets management basics",
      "url": "https://security.example.net/secrets-basics",
      "host": "security.example.net",
      "snippet": "Never commit keys to a repository.",
      "published_at": "2026-06-12",
      "content_status": "ok",
      "content": "# Secrets management basics\n\n**Never** commit keys to a repository...",
      "word_count": 1310
    },
    {
      "position": 4,
      "title": "API key best practices",
      "url": "https://dev.example.com/api-key-best-practices",
      "host": "dev.example.com",
      "snippet": "Scope each key to one service and one environment.",
      "content_status": "not_requested"
    }
  ]
}
```

*curl*

```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()
for r in resp.json()["results"]:
    print(r["position"], r["content_status"], r["url"])
```

*Node.js*

```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 { results } = await res.json();
for (const r of results) console.log(r.position, r.content_status, r.url);
```

## 搜索网页（GET）

`GET /api/v1/search`

相同的搜索，参数放在查询字符串中并经过 URL 编码。`include_domains` 等列表写成一个逗号分隔的值。适合快速测试或只能发送 GET 请求的工具。示例只请求结果（`read=0`）。

认证：API 密钥放在 `Authorization: Bearer API_KEY` 请求头中。

**参数**

| 名称 | 位置 | 类型 | 是否必需 | 描述 |
| --- | --- | --- | --- | --- |
| `q` | query | string | 是 | 搜索查询，URL 编码，1 到 400 个字符。 |
| `max_results` | query | integer | 否 | 1 到 20。默认 5。 |
| `read` | query | integer | 否 | 0 到 10。默认 3；4 或更多消耗 2 积分。 |
| `format` | query | string | 否 | `markdown`（默认）或 `text`。 |
| `max_chars` | query | integer | 否 | 每页 500 到 50,000。默认 6,000。 |
| `topic` | query | string | 否 | `web`（默认）或 `news`。 |
| `time_range` | query | string | 否 | `day`、`week`、`month` 或 `year`。 |
| `country` | query | string | 否 | ISO 3166-1 alpha-2 代码。默认 `us`。 |
| `language` | query | string | 否 | 语言代码。默认 `en`。 |
| `include_domains` | query | string | 否 | 逗号分隔的列表，最多 20 个域名。 |
| `exclude_domains` | query | string | 否 | 逗号分隔的列表，最多 20 个域名。 |
| `api_key` | query | string | 否 | 你的密钥，用于不发送 `Authorization` 请求头时。 |

**响应** `200`

```json
{
  "query": "postgres connection pooling",
  "created_at": "2026-10-22T10:21:47Z",
  "credits_used": 1,
  "results": [
    {
      "position": 1,
      "title": "Connection pooling explained",
      "url": "https://docs.example.com/db/pooling",
      "host": "docs.example.com",
      "snippet": "A pool keeps a few database connections open and lends them to requests.",
      "content_status": "not_requested"
    },
    {
      "position": 2,
      "title": "Sizing a connection pool",
      "url": "https://blog.example.org/pool-size",
      "host": "blog.example.org",
      "snippet": "Start small: the right size depends on cores and disk, not on traffic.",
      "published_at": "2026-03-04",
      "content_status": "not_requested"
    }
  ]
}
```

*curl*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=postgres connection pooling" \
  -d max_results=10 -d read=0
```

*Python*

```python
import os
import requests

resp = requests.get(
    "https://llmwebsearch.com/api/v1/search",
    headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]},
    params={"q": "postgres connection pooling", "max_results": 10, "read": 0},
    timeout=60,
)
print([r["url"] for r in resp.json()["results"]])
```

*Node.js*

```javascript
const params = new URLSearchParams({ q: 'postgres connection pooling', max_results: '10', read: '0' });
const res = await fetch(`https://llmwebsearch.com/api/v1/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}` },
});
console.log((await res.json()).results.map((r) => r.url));
```

## 如何获取不含任何页面内容的结果？

将 `read` 设为 `0`。这样每个结果都会返回标题、URL、主机、摘要和日期，以及 `content_status: "not_requested"`。响应体积小得多，适用于 agent 只需要挑选哪些链接重要的情况。

价格仍为 1 积分，与读取最多 3 个页面相同。常见模式是先进行一次 `read=0` 搜索做初选，然后对模型选中的两三个 URL 发起一次 [extract 调用](https://llmwebsearch.com/zh/docs/extract/)。

## 搜索何时消耗 2 积分？

当 `read` 在 4 到 10 之间时。读取更多页面需要我们这边做更多工作，所以价格翻倍一次，并在最多 10 个页面以内保持 2 积分。

每个响应中的 `credits_used` 显示该次调用的费用。因 robots.txt 规则或拒绝而无法读取的页面，不会降低或提高该价格。如果你大多数时候只需要少量完整页面，请将 `read` 保持为 3，并在偶尔需要额外页面时调用 `/extract`。

## 如何搜索近期新闻？

发送 `topic: "news"` 和 `time_range`。结果便来自新闻文章，`time_range` 只保留过去 `day`、`week`、`month` 或 `year` 内的文章。当文章或搜索结果标明日期时，会填入 `published_at`。

相同的时效过滤也适用于 `topic: "web"`。它适用于近期发布或价格变动之类的问题，因为旧页面会误导模型。

*过去一周的新闻，读取前 3 篇文章*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database release security fix", "topic": "news", "time_range": "week", "read": 3}'
```

## 如何将结果限制在特定网站？

在 `include_domains` 中列出它们，最多 20 条。只保留主机为这些域名之一或其子域名之一的结果：`example.com` 也会匹配 `docs.example.com`。反过来使用 `exclude_domains`，例如从结果中排除你自己的网站。

在 POST 请求体中，这两个字段都是 JSON 数组。在 GET 请求中，将它们写成一个逗号分隔的值。查询本身也可以携带 `site:` 运算符；它会按原样传给搜索。

## 国家和语言会改变什么？

`country` 设置搜索运行的地点，使用两位字母代码，例如 `us`、`de` 或 `br`。排名因国家而异，尤其是本地服务、价格和法规方面。`language` 设置结果的语言，例如 `en`、`fr` 或 `pt-BR`。

两者默认均为美国和英语。当 agent 为一个市场的用户服务时，请同时设置它们：一位询问税务规则的德国用户想要 `country: "de"` 和 `language: "de"`。

## 会返回多少页面文本？

每页最多 `max_chars` 个字符，默认 6,000，范围为 500 到 50,000。该上限保护模型的上下文窗口：3 个页面各 6,000 字符，约相当于 4,500 个英文 token。

`word_count` 统计的是截断前的完整提取文本，因此你可以判断页面是否被裁剪过。当某个答案需要一份长文档时，先用较低上限搜索，然后通过 `/extract` 用更高上限单独抓取该页面。慢速页面不会被无限等待：15 秒后它会以 `fetch_timeout` 返回，不含内容。

## 搜索端点：常见问题

### 我应该用 POST 还是 GET？

在代码中用 POST，因为 JSON 数组和长查询在请求体中更简单。GET 适合在终端里快速测试，或用于只发送查询字符串的工具。两者返回相同的响应，费用也相同。

### 我可以请求超过 20 个结果吗？

不可以。每次调用最多 20 个。Agent 很少需要更多：用改写后的查询进行第二次搜索，通常比长列表带来更好的来源。

### 页面是逐个读取的吗？

不是，是并行读取。15 秒内未响应的页面会以 `fetch_timeout` 返回且不含内容，因此一个慢速网站不会拖住整个响应。

### 哪个搜索引擎产生这些结果？

结果来自你调用当下执行的实时网页搜索，按搜索引擎的排名顺序返回；不提供任何来自旧索引的内容。我们不公布由哪些上游提供商执行搜索。

---

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