# 选择端点

> 根据你掌握的信息和需要的结果，选择合适的 Search1API 端点。

Canonical URL: https://s1.dev/zh/docs/guides/choosing-an-endpoint

先回答两个问题：

1. 你手上有的是一个主题、一个 URL，还是一整个站点？
2. 你需要的是链接、可读文本、结构化字段，还是页面列表？

## 端点对照表

| 你的起点 | 你需要什么 | 使用 |
| --- | --- | --- |
| 一个主题或问题 | 排好序的网页 | [`POST /search`](https://s1.dev/zh/docs/basic/search) |
| 一个主题或问题 | 排好序的网页及其全文 | [`POST /search`](https://s1.dev/zh/docs/basic/search) 配合 `crawl_results` |
| 一个用自然语言描述的问题 | 来自问题所需引擎的相关结果 | [`POST /ask`](https://s1.dev/zh/docs/basic/ask) |
| 一个时事事件 | 来自新闻来源的近期报道 | [`POST /news`](https://s1.dev/zh/docs/basic/news) |
| 一个 URL | 可读的页面内容 | [`POST /crawl`](https://s1.dev/zh/docs/basic/crawl) |
| 一个 URL | 渲染后的 PNG、JPEG 或 WebP 图片 | [`POST /screenshot`](https://s1.dev/zh/docs/basic/screenshot) |
| 一个 URL | 符合 JSON Schema 的字段 | [`POST /extract`](https://s1.dev/zh/docs/advanced/extract) |
| 一个站点 | 站点的 URL 列表 | [`POST /sitemap`](https://s1.dev/zh/docs/advanced/sitemap) |
| 一个站点 | 多个页面的内容 | [`POST /deepcrawl`](https://s1.dev/zh/docs/advanced/deepcrawl) |
| 没有查询词 | GitHub 或 Hacker News 热门 | [`POST /trending`](https://s1.dev/zh/docs/advanced/trending) |

## 主题还是 URL：search 与 crawl

需要发现相关页面时，使用 `/search`。已经知道要读哪个页面时，使用 `/crawl`。

如果你从一个主题出发，但同时需要来源原文，请在 `/search` 上设置 `crawl_results`。Search1API 会在同一个请求中抓取排名靠前的结果。请求写法请参阅[优化搜索结果](https://s1.dev/zh/docs/guides/improving-search-results#read-the-results-not-just-the-snippets)。

`/crawl` 适用于任何公开 URL。对于少数主流网站，专用解析器或数据源路径能返回比通用提取更干净、更结构化的输出，详见[专用站点解析器](https://s1.dev/zh/docs/guides/site-parsers)。

## 自己选择引擎：search 与 ask

如果你知道该查询哪个引擎、要发送什么关键词，使用 `/search`。它会原样返回该引擎的排序结果。

如果合适的来源取决于问题本身，例如社区讨论、代码、论文或视频，使用 `/ask`。它会选择最多五个引擎和一个时间范围，并行搜索，只保留被判定为相关的结果，因此智能体读到的无关结果更少，消耗的 token 也更少。每次请求消耗 5 积分，而 `/search` 为 1 积分。

## 文本还是字段：crawl 与 extract

如果模型或人需要以文本形式阅读页面，例如摘要、问答或 RAG 入库，使用 `/crawl`。

如果你的应用需要结构固定、带类型的字段，使用 `/extract`。你提供 URL、提取提示词和 JSON Schema，端点返回符合该 Schema 的数据。

如果你打算先抓取页面、再立刻让模型把它转换为字段，`/extract` 可以把这两步合并为一步。

## 页面内容还是像素：crawl 与 screenshot

如果你需要把页面作为可读文本，提供给智能体、搜索索引、摘要或 RAG 流水线，使用 `/crawl`。

如果布局和视觉状态很重要，例如链接预览、视觉回归测试的输入、页面图片存档或视觉模型的输入，使用 `/screenshot`。它会在托管浏览器中渲染页面，并直接返回图片字节。

## URL 列表还是站点内容：sitemap 与 deepcrawl

使用 `/sitemap` 来发现一个站点包含哪些 URL。它会同步返回链接，适合由你的应用来决定下一步要获取哪些页面。

需要多个页面的内容时，使用 `/deepcrawl`。它以异步方式运行：发起请求后返回 `202 Accepted` 和一个 `taskId`，然后轮询 `GET /deepcrawl/status/{taskId}`，直到任务完成。

## 全网覆盖还是近期报道：search 与 news

通用的网页发现使用 `/search`。当时效性和新闻类来源是任务的核心时，使用 `/news`。两个端点都支持 `time_range`，但搜索的来源集合不同。

## 常见的智能体工作流

对于研究类和答案生成类智能体：

1. 先用 `/search` 配合较小的 `crawl_results` 值，收集排好序的来源和可读文本。
2. 需要以文本形式重新读取某个 URL 时使用 `/crawl`；工作流需要页面的视觉状态时使用 `/screenshot`。
3. 输出必须遵循稳定的数据 Schema 时，使用 `/extract`。

在决定抓取深度或批量运行工作流之前，请先阅读[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。