搜索 API

Olostep 的 /v1/searches 端点允许你使用自然语言查询搜索网络，并返回一个去重的相关链接列表，包括标题和描述。

发送纯英文查询
从网络各处获取结构化链接
可选地在一次往返中抓取每个返回的 URL，并将 markdown_content / html_content 直接嵌入响应中
按域过滤，控制结果数量，并限制抓取的时间

它将语义搜索网络中的查询并返回结果。有关 API 详细信息，请参阅搜索端点 API 参考。

安装

pip install olostep

npm install olostep

# curl 在 macOS、Linux 和 Windows 上默认可用

npm install node-fetch

pip install requests

基本用法

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

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create("最佳答案引擎优化初创公司")

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

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const search = await client.searches.create('最佳答案引擎优化初创公司')

console.log(search.id, search.links.length)

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "最佳答案引擎优化初创公司"
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: '最佳答案引擎优化初创公司'
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "最佳答案引擎优化初创公司"
}
headers = {"Authorization": "Bearer <YOUR_API_KEY>", "Content-Type": "application/json"}

response = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

请求参数

字段	类型	必需	默认值	描述
`query`	string	是	—	自然语言的搜索查询。
`limit`	integer	否	`12`	去重后返回的最大链接数量。必须在 `1` 和 `25` 之间。
`include_domains`	string[]	否	`[]`	限制结果到这些域名。仅限主机名 — 自动去除前导 `http(s)://` 和尾部斜杠。
`exclude_domains`	string[]	否	`[]`	排除来自这些域名的结果。仅限主机名 — 自动去除前导 `http(s)://` 和尾部斜杠。
`scrape_options`	object	否	—	提供时，每个返回的链接也会被抓取，其内容嵌入响应中。参见下文 scrape_options。
`fast_mode`	boolean	否	`false`	请求直接、低延迟的搜索，使用你的查询原文。默认模式执行更广泛的搜索以获得更广的结果覆盖。

限制结果数量

{
  "query": "OpenAI 的 Sora 关闭发生了什么？",
  "limit": 5
}

按域过滤

include_domains 将结果缩小到白名单；exclude_domains 过滤掉不需要的来源。它们可以结合使用。

{
  "query": "OpenAI Sora 关闭分析",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

scrape_options

传递 scrape_options 以并行抓取每个返回的 URL，并直接在每个链接上嵌入渲染的内容。这比分别调用 /v1/searches 和 /v1/scrapes 节省了一次往返。

{
  "query": "OpenAI 的 Sora 关闭发生了什么？",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}

字段	类型	默认值	描述
`formats`	string[]	`["markdown"]`	附加到每个链接的输出格式。对于 `/v1/searches`，仅支持 `"html"` 和 `"markdown"`。传递 `["html", "markdown"]` 以接收两者。
`remove_css_selectors`	string	`"default"`	转发到 `/v1/scrapes`。`"default"` 去除导航/页脚/脚本/样式/svg/对话框噪音。使用 `"none"` 禁用，或传递一个 JSON 字符串化的选择器数组以移除。
`timeout`	integer	`25`	整个抓取阶段的时间预算，单位为秒。必须在 `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="OpenAI 的 Sora 关闭发生了什么？",
    limit=5,
    scrape_options={"formats": ["markdown"], "timeout": 25},
)

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

import Olostep, { Format } from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const search = await client.searches.create({
  query: "OpenAI 的 Sora 关闭发生了什么？",
  limit: 5,
  scrapeOptions: {
    formats: [Format.MARKDOWN],
    timeout: 25
  }
})

for (const link of search.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "OpenAI 的 Sora 关闭发生了什么？",
    "limit": 5,
    "scrape_options": {
      "formats": ["markdown"],
      "timeout": 25
    }
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: "OpenAI 的 Sora 关闭发生了什么？",
    limit: 5,
    scrape_options: {
      formats: ['markdown'],
      timeout: 25
    }
  })
})
const data = await res.json()
for (const link of data.result.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "OpenAI 的 Sora 关闭发生了什么？",
  "limit": 5,
  "scrape_options": {
    "formats": ["markdown"],
    "timeout": 25
  }
}
headers = {"Authorization": "Bearer <YOUR_API_KEY>", "Content-Type": "application/json"}

response = requests.post(endpoint, json=payload, headers=headers)
data = response.json()
for link in data["result"]["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": "OpenAI 的 Sora 关闭发生了什么？",
  "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 将关闭 Sora 视频平台",
        "description": "OpenAI 表示将停止其 Sora 应用...",
        "markdown_content": "# OpenAI 将关闭 Sora 视频平台\n\nOpenAI 表示将停止..."
      },
      {
        "url": "https://www.reddit.com/r/OutOfTheLoop/comments/1s2u847/whats_going_on_with_openais_sora_shutting_down/",
        "title": "OpenAI 的 Sora 关闭发生了什么？",
        "description": "Reddit 讨论关闭的线程。",
        "markdown_content": "# OpenAI 的 Sora 关闭发生了什么？\n\n*r/OutOfTheLoop · u/rm-minus-r · 1mo ago*\n\n..."
      }
    ]
  }
}

result.links 中的每个链接包含：

字段	类型	描述
`url`	string	搜索结果的 URL。
`title`	string	结果页面的标题。
`description`	string	描述结果的简短片段。
`markdown_content`	string	页面的 Markdown 内容。仅当 `scrape_options.formats` 包含 `"markdown"` 时存在。抓取失败、为空或超时时为 `null`。
`html_content`	string	页面的 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))

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const search = await client.searches.get('search_9bi0sbj9xa')
console.log(search.id, search.links.length)

curl -s "https://api.olostep.com/v1/searches/search_9bi0sbj9xa" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

查看获取搜索以获取完整详细信息。

存储

搜索的存储文件默认保留 7 天。在 POST /v1/searches 上传递一个 storage 对象以保持更长时间或无限期。该设置涵盖了 result.json_hosted_url 上的托管 JSON 文件，并且在设置 scrape_options 时，涵盖了为每个链接抓取的内容。

参数	类型	默认值	描述
`storage.expires_in`	`string`	`7d`	保留存储文件的时间。可选值为 `7d`、`10d`、`30d`、`60d`、`90d`、`180d`、`365d` 或 `never`（无限期）。

省略 storage，或发送不带 expires_in 的 storage，则使用 7d。创建响应和 GET /v1/searches/{search_id} 都包含生效的值：

"storage": { "expires_in": "30d" }

cURL

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "最佳开源向量数据库",
    "storage": { "expires_in": "30d" }
  }'

无效值返回 400：

{
  "type": "invalid_request_error",
  "message": "Invalid storage.expires_in. Allowed values: \"7d\", \"10d\", \"30d\", \"60d\", \"90d\", \"180d\", \"365d\", \"never\".",
  "code": "invalid_storage_expires_in"
}

价格

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

请求	`credits_consumed`
仅搜索	`5`
搜索 + 5 个抓取页面（每个 1 个积分）	`10`

开始使用

功能

余额与账单

安装

基本用法

请求参数

限制结果数量

按域过滤

scrape_options

行为

带抓取的示例

响应

检索过去的搜索

存储

价格

​安装

​基本用法

​请求参数

​限制结果数量

​按域过滤

​scrape_options

​行为

​带抓取的示例

​响应

​检索过去的搜索

​存储

​价格

安装

基本用法

请求参数

限制结果数量

按域过滤

scrape_options

行为

带抓取的示例

响应

检索过去的搜索

存储

价格