---
title: "Search API：網頁與新聞檢索"
description: "透過 Lazu search backends 呼叫 provider-neutral 的 POST /v1/search。"
source: https://lazu.ai/docs/zh-TW/endpoints/search
updated: 2026-10-02
---

# Search

**POST** `/v1/search`

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

## 請求範例

```bash
curl https://api.lazu.ai/v1/search \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest OpenAI web search API changes",
    "type": "web",
    "max_results": 5,
    "backend": "auto"
  }'
```

## 回應範例

```json
{
  "query": "latest OpenAI web search API changes",
  "results": [
    {
      "title": "OpenAI ships web search API",
      "url": "https://example.com/news",
      "snippet": "…",
      "score": 0.92,
      "source": "tavily"
    }
  ],
  "usage": {
    "web_search_requests": 1,
    "web_search_billable_units": 1
  },
  "provider_trace": { "backend": "tavily" },
  "route_receipt": {
    "selection": "auto",
    "selected_backend": "search_tavily",
    "chose_provider": "tavily",
    "candidates": ["search_tavily"],
    "decision_reason": "matched web_search capability"
  }
}
```

## 返回什麼

- **標準化結果** — 不同 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

- `query` `string` (必填) — 搜尋 query。當前 MVP 每次請求支援一個 query。
- `type` `string` (可選) — 搜尋類型，預設 `web`。 取值: `web`, `news`
- `backend` `string` (可選) — `auto`、provider 名稱如 `tavily` 或 
  `serper`， 或已設定的 backend ID/name。預設 `auto`。
- `region` `string` (可選) — 地區 hint。Serper 會映射到 `gl`。
- `language` `string` (可選) — 語言 hint，例如 `en` 或 `zh-TW`。
- `time_range` `string` (可選) — 時間範圍 hint。provider 不支援時可能忽略。 取值: `day`, `week`, `month`, `year`
- `max_results` `integer` (可選) — 返回結果數。預設 `10`，並受 backend policy 上限約束。
- `search_depth` `string` (可選) — provider 深度 hint。Tavily `advanced` 會消耗 2 個計費 unit。 取值: `basic`, `advanced`
- `include_answer` `boolean` (可選) — selected backend 返回 answer 時一併返回。Lazu 不會在這個 endpoint
  內生成最終答案。
- `include_raw_content` `boolean` (可選) — provider 返回原文或清洗正文時是否透出，預設 `false`。
- `include_domains` `string[]` (可選) — 限制搜尋網域。token 級 domain allowlist 仍會生效。
- `exclude_domains` `string[]` (可選) — 排除網域，取決於 selected backend 是否支援。
- `include_provider_payload` `boolean` (可選) — 返回 provider 原始 payload，主要用於排障。預設 `false`。
- `provider_options` `object` (可選) — 進階 provider passthrough。只會使用當前 provider 對應物件，例如 
  `{"serper":{"tbs":"qdr:d"}}`。

## 響應

**Search response**

```json
{
"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_requests` `integer` — Lazu 搜尋請求次數，通常為 `1`。
- `usage.web_search_billable_units` `integer` — 實際計費使用的 provider unit。Tavily basic 為 1，Tavily advanced 為 2，
  Serper 和 Jina 通常為 1 個成功 query。
- `provider_trace.backend` `string` — 路由後實際選中的 provider。
- `route_receipt` `object` (可選) — 候選、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。

## 相關頁面

- [計費規則](https://lazu.ai/docs/zh-TW/billing)
- [請求詳情](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)
- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)