跳转到主要内容
Olostep 的 /v1/searches 端点允许你使用自然语言查询搜索网络，并返回去重后的相关链接列表，包含标题和描述。
  • 用简单的英语发送查询
  • 从整个网络获取结构化链接
  • 可选地在一次往返中抓取每个返回的 URL，并将 markdown_content / html_content 直接嵌入响应中
  • 按域过滤，控制结果数量，并限制抓取的时间
它将语义地在网络上搜索查询并返回结果。 有关 API 详细信息，请参阅 搜索端点 API 参考。

​
安装

pip install olostep

​
基本用法

发送自然语言查询并接收相关链接列表。 
from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create("Best Answer Engine Optimization startups")

print(search.id, len(search.links))

​
请求参数

字段类型必需默认值描述
querystring是—自然语言的搜索查询。
limitinteger否12去重后返回的最大链接数。必须在 1 到 25 之间。
include_domainsstring[]否[]将结果限制在这些域中。仅裸主机 — 自动去除前导 http(s):// 和尾部斜杠。
exclude_domainsstring[]否[]排除来自这些域的结果。仅裸主机 — 自动去除前导 http(s):// 和尾部斜杠。
scrape_optionsobject否—提供时，每个返回的链接也会被抓取，其内容嵌入在响应中。参见下文的 scrape_options。

​
限制结果数量

{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 5
}

​
按域过滤

include_domains 将结果缩小到白名单；exclude_domains 过滤掉不需要的来源。它们可以结合使用。 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

传递 scrape_options 以并行抓取每个返回的 URL，并将渲染的内容直接嵌入到每个链接上。这比分别调用 /v1/searches 和 /v1/scrapes 节省了一次往返。 
{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}
字段类型默认值描述
formatsstring[]["markdown"]附加到每个链接的输出格式。对于 /v1/searches，仅支持 "html" 和 "markdown"。传递 ["html", "markdown"] 以接收两者。
remove_css_selectorsstring"default"转发到 /v1/scrapes。"default" 去除导航/页脚/脚本/样式/svg/对话框噪声。使用 "none" 禁用，或传递一个 JSON 字符串化的选择器数组以移除。
timeoutinteger25整个抓取阶段的时间预算（以秒为单位）。必须在 1 到 60 之间。在此时间结束后，搜索立即返回 — 对于尚未完成的任何链接，其内容字段将为 null。

​
行为

  • 所有链接都是并行抓取的。timeout 限制整个批次，而不是每个单独的链接。
  • 每个链接的抓取失败（网络错误、单个页面超时）会使该链接的 markdown_content / html_content 为 null，而其他链接正常返回。
  • 如果全局 timeout 在所有抓取完成之前到期，搜索将立即响应已完成的链接 — 已完成的抓取保留其内容；正在进行中的返回 null 内容。
  • 对于 reddit.com/.../comments/... URL，请求会自动通过 @olostep/reddit-post 解析器路由，并将结构化 JSON 渲染为干净的 markdown + 基本 HTML。
  • 如果组合的内联内容超过 9MB，内容字段将为空，result.size_exceeded 将设置为 true，你可以从 result.json_hosted_url 获取完整的负载。

​
带抓取的示例

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create(
    query="What's going on with OpenAI's Sora shutting down?",
    limit=5,
    scrape_options={"formats": ["markdown"], "timeout": 25},
)

for link in search.links:
    print(link["url"], "—", len(link.get("markdown_content") or ""), "chars")

​
响应

你将收到一个 search 对象作为响应。search 对象包含一个 id，你原始的 query，credits_consumed，以及一个包含 links 列表的 result。 
{
  "id": "search_9bi0sbj9xa",
  "object": "search",
  "created": 1760327323,
  "metadata": {},
  "query": "What's going on with OpenAI's Sora shutting down?",
  "credits_consumed": 10,
  "result": {
    "json_content": "...",
    "json_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/search_9bi0sbj9xa.json",
    "size_exceeded": false,
    "credits_consumed": 10,
    "links": [
      {
        "url": "https://www.bbc.com/news/articles/c3w3e467ewqo",
        "title": "OpenAI to shut down Sora video platform",
        "description": "OpenAI says it will discontinue its Sora app...",
        "markdown_content": "# OpenAI to shut down Sora video platform\n\nOpenAI says it will discontinue..."
      },
      {
        "url": "https://www.reddit.com/r/OutOfTheLoop/comments/1s2u847/whats_going_on_with_openais_sora_shutting_down/",
        "title": "What's going on with OpenAI's Sora shutting down?",
        "description": "Reddit thread discussing the shutdown.",
        "markdown_content": "# What's going on with OpenAI's Sora shutting down?\n\n*r/OutOfTheLoop · u/rm-minus-r · 1mo ago*\n\n..."
      }
    ]
  }
}
result.links 中的每个链接包含：
字段类型描述
urlstring搜索结果的 URL。
titlestring结果页面的标题。
descriptionstring描述结果的简短片段。
markdown_contentstring页面的 Markdown 内容。仅当 scrape_options.formats 包含 "markdown" 时存在。抓取失败、为空或超时时为 null。
html_contentstring页面的 HTML 内容。仅当 scrape_options.formats 包含 "html" 时存在。失败/超时时为 null。
完整结果也可以作为托管的 JSON 文件在 result.json_hosted_url 获取 — 当 result.size_exceeded 为 true 时很有用。

​
检索过去的搜索

GET /v1/searches/{search_id} 返回在搜索时保存的内容，包括任何抓取的内容。它是一个纯粹的幂等读取 — 无需重新抓取，无需重新计费。没有 scrape_options 的旧搜索没有每个链接的内容字段。 
from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.get(search_id="search_9bi0sbj9xa")
print(search.id, len(search.links))
有关完整详细信息，请参阅 获取搜索。

​
价格

每次搜索花费 5 积分 用于搜索本身。 当提供 scrape_options 时，每个抓取的页面按标准 /v1/scrapes 费率计费（通常每页 1 积分；某些解析器费用更高）。总费用在 credits_consumed 中返回。 示例：
请求credits_consumed
仅搜索5
搜索 + 5 个抓取页面（每个 1 积分）10