介面 / Retrieval

POSThttps://api.lazu.ai/v1/search

Search

透過 Lazu 統一呼叫 Web 或 News 搜尋。託管版 api.lazu.ai 目前啟用了 Tavily、Serper 和 Jina；自部署管理員也可以透過同一套 Search Backend 系統接入 Exa 或 Brave。

計費搜尋費用取決於所選後端與計費單位。價格與線路 ↗

返回什麼

標準化結果

不同 provider 都會映射成 title、url、 snippet、可選的 content、published_at 、score 和 source。

可稽核路由

響應會返回實際選中的 backend 和 route receipt。請求日誌中也會保存同樣的 routing metadata，方便排障和對帳。

託管版設定

/v1/search 的實作支援 Tavily、Serper、Exa、Jina 和 Brave，但請查看目前顯示的搜尋價格，並在請求詳情核對 web_search 計費明細；不要根據舊示例或部署設定推斷搜尋免費。

Backend	託管版狀態	能力	說明
Tavily	已啟用	`web_search`、`web_fetch`、`answer`	支援 `include_answer` 和 `search_depth`；`advanced` 按 2 units 計算。
Serper	已啟用	`web_search`	會映射 `country` / `region`、`language` 和 `time_range`。
Jina	已啟用	`web_search`、`web_fetch`	使用 `https://s.jina.ai`，較適合 retrieval 風格的 snippet。
Exa / Brave	程式支援	管理員設定後支援 `web_search`	適用於自部署或管理員後續設定的託管環境。

目前託管版 backend 使用預設策略：每次請求最多返回 10 筆結果，上游 timeout 為 8s。如果請求裡的 max_results 更大，Lazu 會按選中的 backend policy 截斷。

請求 Body

querystringrequired

搜尋 query。當前 MVP 每次請求支援一個 query。

typestringnullable

搜尋類型，預設 web。

webnews

backendstringnullable

auto、provider 名稱如 tavily 或 serper，或已設定的 backend ID/name。預設 auto。

regionstringnullable

地區 hint。Serper 會映射到 gl。

languagestringnullable

語言 hint，例如 en 或 zh-TW。

time_rangestringnullable

時間範圍 hint。provider 不支援時可能忽略。

dayweekmonthyear

max_resultsintegernullable

返回結果數。預設 10，並受 backend policy 上限約束。

search_depthstringnullable

provider 深度 hint。Tavily advanced 會消耗 2 個計費 unit。

basicadvanced

include_answerbooleannullable

selected backend 返回 answer 時一併返回。Lazu 不會在這個 endpoint 內生成最終答案。

include_raw_contentbooleannullable

provider 返回原文或清洗正文時是否透出，預設 false。

include_domainsstring[]nullable

限制搜尋網域。token 級 domain allowlist 仍會生效。

exclude_domainsstring[]nullable

排除網域，取決於 selected backend 是否支援。

include_provider_payloadbooleannullable

返回 provider 原始 payload，主要用於排障。預設 false。

provider_optionsobjectnullable

進階 provider passthrough。只會使用當前 provider 對應物件，例如 {"serper":{"tbs":"qdr:d"}}。

響應

Search responsejson

{
"query": "latest OpenAI web search API changes",
"results": [
  {
    "title": "Web search - OpenAI API",
    "url": "https://platform.openai.com/docs/guides/tools-web-search",
    "snippet": "Use web search in the Responses API...",
    "content": null,
    "published_at": null,
    "score": 0.91,
    "source": "web"
  }
],
"usage": {
  "web_search_requests": 1,
  "web_search_billable_units": 1
},
"provider_trace": {
  "backend": "tavily"
},
"route_receipt": {
  "selection": "auto",
  "selected_backend": "tavily",
  "chose_provider": "tavily",
  "candidates": ["tavily:Tavily"],
  "rejected": [],
  "downgraded": false,
  "fallback_count": 0,
  "decision_reason": "selected"
}
}

results[]object[]

標準化搜尋結果。只有請求了 raw content 且 backend 返回時， content 才會填充。

usage.web_search_requestsinteger

Lazu 搜尋請求次數，通常為 1。

usage.web_search_billable_unitsinteger

實際計費使用的 provider unit。Tavily basic 為 1，Tavily advanced 為 2， Serper 和 Jina 通常為 1 個成功 query。

provider_trace.backendstring

路由後實際選中的 provider。

route_receiptobjectnullable

候選、fallback、拒絕原因等路由 metadata，同步寫入請求日誌。

計費

Search backend 的價格來自設定中的 search_price。這個值表示每個 provider billing unit 的 USD 價格，不一定等同於每個 HTTP request 的價格。目前託管版 Tavily、Serper 和 Jina 沒有明確設定 search_price，所以 Lazu 會記錄 web_search usage，但 search line item 費用為 $0；後續管理員設定價格或 provider-cost passthrough 後才會按設定收費。

Backend	Unit 映射
Tavily	`basic` = 1 credit；`advanced` = 2 credits
Serper	1 個成功 query = 1 unit
Jina	1 個成功 query = 1 unit

上游失敗、timeout、參數錯誤會按 Lazu 常規計費規則 refund。