# 响应格式：搜索的每个字段逐一说明

> 搜索 API 响应格式：/search 和 /extract 的每个字段、八个 content_status 取值以及 target_status，附完整示例。无需 KYC，加密货币支付。

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

一次搜索的返回就是一个 JSON 对象：几个描述此次调用的字段，然后是一个按排名排列的 `results` 数组。每条结果会说明其页面是否已被读取，若已读取则附带正文内容。以下是全部字段，以及 agent 应当处理的各种状态。

**快速回答 — LLMWebSearch API 对一次搜索返回什么？**

**LLMWebSearch** 返回 JSON，包含 `query`、`created_at`、`credits_used` 以及一个按排名排列的 `results` 数组。每条结果包含其位置、标题、URL、host 和摘要，以及一个 `content_status`；当它为 `ok` 时，页面的正文内容位于 `content` 中，并带有一个 `word_count`。一次最多读取 3 个页面的搜索花费 1 积分，低至 US$1.20/千次搜索（截至 2026 年 10 月）。无需 KYC；用加密货币支付。

## 哪些字段描述此次调用？

`/search` 响应的顶层。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `query` | string | 我们实际执行的查询，已去除首尾空格 |
| `created_at` | string | 搜索执行的时间，ISO 8601 格式，UTC 时区 |
| `credits_used` | integer | 此次调用的费用：1；当 `read` 为 4 到 10 时为 2 |
| `results` | array | 按排名排列的结果，最优在前，最多 `max_results` 条 |

## 每条结果包含哪些字段？

页面或搜索结果未提供的字段会被省略，而不会以空值发送。

| 字段 | 类型 | 出现时机 | 含义 |
| --- | --- | --- | --- |
| `position` | integer | 始终 | 搜索中的排名，从 1 开始 |
| `title` | string | 始终 | 结果的标题 |
| `url` | string | 始终 | 页面的地址 |
| `host` | string | 始终 | 页面的主机名，便于分组或引用 |
| `snippet` | string | 始终 | 搜索展示的简短摘录 |
| `published_at` | string | 当日期已知时 | 来自页面或搜索结果的发布日期 |
| `content_status` | string | 始终 | 页面是否已读取，若未读取，原因是什么 |
| `content` | string | 当 `content_status` 为 `ok` 时 | 正文内容，格式为 Markdown 或纯文本，在 `max_chars` 处截断 |
| `word_count` | integer | 当 `content_status` 为 `ok` 时 | 整个提取文本中的词数，在截断前统计 |
| `target_status` | integer | 搭配 `target_refused` | 网站返回的 HTTP 状态码，例如 403 或 429 |

## 每个 content_status 分别代表什么？

这些都不会改变本次搜索的价格。它们描述的是单个页面，绝不代表整个调用。

| `content_status` | 含义 | 智能体应当怎么做 |
| --- | --- | --- |
| `ok` | 页面已读取；`content` 保存其正文 | 直接使用并引用 `url` |
| `not_requested` | 结果超出了 `read` 的数量 | 调高 `read`，如有需要可通过 `/extract` 读取 |
| `blocked_by_robots` | 该网站的 robots.txt 不允许我们的读取器访问此页面 | 改用摘要片段或其他来源 |
| `blocked_by_site_policy` | 网站声明了 `Content-Signal: ai-input=no` | 改用摘要片段或其他来源 |
| `target_refused` | 网站拒绝了请求；参见 `target_status` | 不要重试该页面；改用其他来源 |
| `fetch_failed` | DNS、TLS 或连接错误，或页面已不存在 | 尝试其他结果；稍后重试可能成功 |
| `fetch_timeout` | 页面未在 15 秒内响应 | 尝试其他结果；稍后重试可能成功 |
| `unsupported_content` | 该链接是我们无法转换为文本的文件 | 改用摘要片段或其他结果 |

## 完整响应是什么样的？

下方示例请求了 5 条结果，其中前 4 条被读取，因此消耗 2 个积分。结果 1 和 3 已读取。结果 2 所属网站的 robots.txt 阻止了我们的读取器，结果 4 拒绝了请求，结果 5 超出 `read`。标题、URL 和数值仅为示例。

*POST /search 响应（示例）*

```json
{
  "query": "how to rotate api keys without downtime",
  "created_at": "2026-10-22T10:15:04Z",
  "credits_used": 2,
  "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.",
      "content_status": "ok",
      "content": "# Secrets management basics\n\n**Never** commit keys to a repository.",
      "word_count": 1310
    },
    {
      "position": 4,
      "title": "Key management service guide",
      "url": "https://cloud.example.com/kms-guide",
      "host": "cloud.example.com",
      "snippet": "Store keys in a managed vault and rotate them on a schedule.",
      "content_status": "target_refused",
      "target_status": 403
    },
    {
      "position": 5,
      "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"
    }
  ]
}
```

## 哪些结果会得到 not_requested 以外的页面状态？

只有前 `read` 条结果，以及一次 `/extract` 调用中的每一项。这些才是我们的阅读器真正尝试抓取的页面。在 `read` 条之后的所有内容都保持 `not_requested`，无论网站本来会返回什么。

顺序从不改变：阅读器按位置 1、2、3 依次处理，绝不会跳过前面失败的结果去读后面的结果。如果 agent 需要替代一个被拒绝的页面，它可以通过 `/extract` 读取下一条结果。

## extract 响应长什么样？

`/extract` 会返回 `credits_used` 和一个 `results` 数组，顺序与你发送的 URL 一致。每一项包含 `url` 和 `content_status`；启用 `ok` 时会额外返回 `title`、`content` 和 `word_count`，启用 `target_refused` 时会额外返回 `target_status`。不会有 `position`、`host` 或 `snippet`，因为没有运行搜索。

[extract 参考文档](https://llmwebsearch.com/zh/docs/extract/) 提供了一个完整示例，并说明了积分如何计算。

## 如何把结果转换成模型的上下文？

给来源编号，把 URL 放在每个来源旁边，只传模型需要的内容。紧凑的布局效果很好：先 `[1] title — url`，然后是该页面的内容，再是下一个来源。让模型用相同的编号引用。

当某条结果没有内容时，改为给模型它的摘要片段，并说明这只是摘要片段。这样可以避免模型基于它从未见过的页面作答。[Python 页面](https://llmwebsearch.com/zh/docs/python/) 有一个简短的循环，能在 token 预算内完成上述所有操作。

## 响应格式：常见问题

### 内容始终是 Markdown 吗？

默认是 Markdown。发送 `format: "text"` 可以获得不含标记的纯文本，例如当你只需统计字数或对页面分类时。字段名仍是 `content`。

### 为什么有些结果缺少 published_at？

许多页面没有标注日期，有些搜索结果也不显示日期。这种情况下该字段会被省略，因此使用前请先检查它是否存在。

### 以后会出现新字段吗？

会。在版本 1 中，字段可能会新增，但绝不会重命名或删除。请让你的解析器忽略它不认识的字段。

### 内容会存储在你们这边吗？

不会。我们不会用你的查询或 API 返回的内容训练任何模型，也不会自行添加任何禁止存储结果的规则；你读取的页面所属网站的权利仍然适用。我们的请求日志只保留每次调用的简短记录，详见[隐私页面](https://llmwebsearch.com/zh/privacy/)。

---

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