# Read API 响应格式，逐字段说明

> Read API 响应格式：为单个页面返回的每个字段，从 markdown 和 word_count 到 final_url 和 rendered，以及任务结果。无需 KYC，使用加密货币支付。

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

每次 `/read` 调用都会返回一个 JSON 对象：你想要格式的页面内容、其 metadata，以及三个告诉你发生了什么和消耗了多少的字段。任务结果复用同一个对象。

**快速回答 — WebReaderAPI 的读取响应包含什么？**

**WebReaderAPI** `/read` 响应包含 `markdown`（或 `text` 或 `html`）格式的页面内容、其 metadata（`title`、`description`、`author`、`published_at`、`language`、`site_name`、`word_count`），以及抓取的相关事实：`final_url`、`status_code`、`rendered` 和 `credits_used`。普通页面使用 1 积分，截至 2026 年 10 月起为 US$0.07/千页。无需 KYC；使用加密货币支付。

## 哪些字段描述抓取过程？

这些字段在成功响应中始终存在。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `url` | string | 你发送的地址 |
| `final_url` | string | 实际读取的地址，在重定向之后（最多 5 次） |
| `status_code` | integer | 网站最终地址返回的 HTTP 状态码，通常为 200 |
| `fetched_at` | string | 抓取时间，ISO 8601 格式，UTC 时间 |
| `rendered` | boolean | 当由无头浏览器构建页面时，此值为 `true` |
| `credits_used` | integer | 此页面计费的积分：1，使用浏览器时 2，使用 `country` 时另加 10；PDF 每开始 10 页计 1 |

## 哪些字段描述页面？

元数据来自页面本身：其 title 标签、meta 标签、结构化数据和可见署名。页面未提供的字段将缺失，因此使用前请先判断其是否存在。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `title` | string | 页面或文章标题 |
| `description` | string | 页面对自身的摘要 |
| `language` | string | 内容的语言代码，例如 `en` 或 `de` |
| `author` | string | 页面上标明的作者 |
| `published_at` | string | 页面声明的发布日期 |
| `site_name` | string | 网站自身的名称 |
| `word_count` | integer | 返回内容中的词数，在正文提取后、`max_chars` 之前统计 |

## 内容本身在哪里？

返回一个内容字段，以其名称对应你所选的 `format`。

| 字段 | When | Content |
| --- | --- | --- |
| `markdown` | `format=markdown`（默认） | Markdown 格式的标题、段落、列表、表格和链接；使用 `include_images=true` 时还包括图片 |
| `text` | `format=text` | 纯文本，段落之间以空行分隔 |
| `html` | `format=html` | 主体内容的清理后 HTML，不含脚本、样式或广告 |
| `links` | `include_links=true` | 页面上找到的链接的 `{url, text}` 列表，绝对 URL |

*完整响应（数值仅为示例）*

```json
{
  "url": "https://example.com/guides/compost",
  "final_url": "https://example.com/guides/compost-at-home",
  "status_code": 200,
  "fetched_at": "2026-10-22T10:02:44Z",
  "rendered": false,
  "credits_used": 1,
  "title": "Compost at home: a beginner's guide",
  "description": "What to put in a compost bin, and what to leave out.",
  "language": "en",
  "author": "Sam Rivera",
  "published_at": "2026-09-14",
  "site_name": "Example Garden",
  "markdown": "# Compost at home: a beginner's guide\n\nA compost bin turns kitchen scraps into soil...\n\n## What goes in\n\n- Fruit and vegetable peels\n- Coffee grounds\n\nSee also [Choosing a bin](https://example.com/guides/bins).",
  "word_count": 1184,
  "links": [
    { "url": "https://example.com/guides/bins", "text": "Choosing a bin" }
  ]
}
```

## 如何区分渲染页面和普通页面？

查看 `rendered`。使用 `render=auto` 时，API 先读取原始 HTML；只有当该 HTML 文本过少时才启动浏览器，随后将 `rendered` 设为 `true`，将 `credits_used` 设为 2。如果你经常读取的某个站点总是以渲染形式返回，可以一开始就发送 `render=true`：成本相同，而且能省去一次无用的首步。

如果页面返回时未渲染但内容偏少，将 `word_count` 与你在浏览器中看到的内容进行比较。计数偏低通常意味着内容需要 JavaScript；用 `render=true` 重试一次。

## 为什么 final_url 可能与 url 不同？

因为站点会重定向。短链接、旧地址、缺少末尾斜杠或语言切换都会把你带到别处。API 最多跟随 5 次重定向，并在 `final_url` 中报告它最终读取的地址。

在 RAG 索引中，将 `final_url` 存储为文档的 canonical 来源。两个不同的 `url` 值如果最终都指向同一个 `final_url`，就是同一个页面，因此你可以在嵌入之前去掉重复项。

## 任务结果是什么样的？

`GET https://webreaderapi.com/api/v1/jobs/{job_id}` 返回 `job_id`、`status`（`queued`、`running` 或 `done`）、`results`、`next_cursor` 以及该任务的运行中 `credits_used`。`results` 的每一项为两种形态之一：

- 一个完整的 `/read` 响应，完全如上所述，对应已读取的页面；
- `{url, error}` 对应未读取的页面，其中 `error` 具有与 [API error](https://webreaderapi.com/zh/docs/errors/) 相同的 `code` 和 `message`。

当还有更多结果就绪时，`next_cursor` 会出现；将其作为 `cursor` 回传以获取这些结果。[batch and crawl page](https://webreaderapi.com/zh/docs/crawl/) 有完整的轮询循环。

*任务结果页面（数值仅为示例）*

```json
{
  "job_id": "job_5c1e8a90d2",
  "status": "done",
  "results": [
    { "url": "https://example.com/blog/post-1", "final_url": "https://example.com/blog/post-1", "status_code": 200, "rendered": false, "credits_used": 1, "title": "Post one", "markdown": "# Post one\n\n...", "word_count": 802 },
    { "url": "https://example.org/members/area", "error": { "code": "target_refused", "message": "The site refused the request.", "target_status": 403 } }
  ],
  "credits_used": 1
}
```

## 错误响应是什么样的？

错误返回时带有 400 或以上的 HTTP 状态码，以及 JSON 正文 `{"error": {"code", "message"}}`。当站点本身拒绝了请求时，`target_status` 给出站点发送的状态码。错误不计费。[errors page](https://webreaderapi.com/zh/docs/errors/) 列出了每个代码及其原因，以及重试是否有帮助。

## 响应格式：常见问题

### 设置 max_chars 时 Markdown 会被截断吗？

会。content 字段在该字符数处停止。`word_count` 仍描述整个提取内容，因此你可以看到省略了多少。

### 为什么缺少 author 或 published_at？

因为页面没有以可读取的方式说明。许多页面不提供作者或日期。缺失的字段会被省略，而不是返回空值。

### Markdown 中的链接是绝对的吗？

`links` 列表中的链接是绝对的。编写代码以接受 Markdown 正文中的两种形式，并将相对链接基于 `final_url` 解析。

### 我能获取整个页面的原始 HTML 吗？

最接近的是 `format=html`，提供 `main_content=false`，它会返回去除脚本和样式的整页内容。v1 不包含原始逐字节 HTML。

---

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