網路搜尋

Web 搜尋

相容 Tavily 的 `POST /v1/search`，回傳排序結果，不呼叫模型。可使用 `Authorization: Bearer <BazaarLink key>`，或在 JSON body 傳 `api_key`。基礎 URL 為 `https://api.bazaarlink.ai/v1`，舊版入口 `https://bazaarlink.ai/api/v1` 也支援。所有 frozen OpenAPI 欄位都會驗證；未知欄位會忽略。搜尋深度、日期、語言、網域、圖片、答案與 raw content 選項都依下方契約處理。免費額度需已驗證 email，按 UTC 每日重置；未有餘額的帳戶與有餘額的帳戶額度不同，實際 N/M 數值由資料庫的 `getPublicFreeSearchAllowance()` 提供，請查看 pricing page 的目前每日額度。無餘額且免費額度用完時回傳 432。客戶價格為 credit 數乘以 admin 設定的每 credit 價格，不在文件中寫死美元金額；請查看 pricing page，並讀取每個回應的 `usage.cost`。Python 範例使用 `TavilyClient(api_key=..., api_base_url='https://api.bazaarlink.ai/v1')`；JS 使用 `tavily({ apiKey, apiBaseURL })`；LangChain 使用 `TavilySearch(api_base_url=...)`。

POST/v1/search

驗證

Authorization必填

string · header

在 Authorization 標頭以 Bearer token 傳入 API 金鑰。

Body

query必填

string

要執行的搜尋查詢。

required; non-empty search query

Example: who is Leo Messi?

search_depth

string

控制延遲、相關性與內容產生方式。預設為 `basic`；`basic`、`fast`、`ultra-fast` 各 1 credit，`advanced` 為 2 credits。

default: basic

advancedbasicfastultra-fast

chunks_per_source

integer

每個來源可回傳的相關內容片段數。預設 3，範圍為 1–3；適用於 `advanced`、`basic`、`fast`。

default: 3; 1..3

max_results

integer

要回傳的搜尋結果數量。預設 10，允許 0–20。

default: 10; 0..20

Example: 1

topic

string

搜尋主題。預設 `general`；`news` 適合即時新聞，`finance` 適合金融內容。

default: general

generalnewsfinance

time_range

string

依時間範圍過濾發布或更新日期。預設未設定；可用 `day`、`week`、`month`、`year` 或 `d`、`w`、`m`、`y`。

default: null

dayweekmonthyeardwmy

start_date

string

只回傳指定日期之後發布或更新的結果。格式必須為 YYYY-MM-DD。

default: null; format YYYY-MM-DD

Example: 2025-02-09

end_date

string

只回傳指定日期之前發布或更新的結果。格式必須為 YYYY-MM-DD。

default: null; format YYYY-MM-DD

Example: 2025-12-29

include_published_date

boolean

在每個結果中包含估計的發布或更新日期。`news` 主題會自動啟用。預設 `false`。

default: false

filter_by_published_date

boolean

移除不在 `time_range`、`start_date`、`end_date` 範圍內或沒有可辨識日期的結果。預設 `false`；設為 `true` 也會啟用 `include_published_date`。

default: false

include_answer

boolean | string

包含查詢的 LLM 產生答案。預設 `false`；可用布林值或 `basic`、`advanced`。

default: false

basicadvanced

include_raw_content

boolean | string

包含每個結果的清理後 HTML 內容。預設 `false`；可用布林值或 `markdown`、`text`。

default: false

markdowntext

include_images

boolean

包含頂層查詢圖片，以及每個結果中的來源圖片。預設 `false`。

default: false

include_image_descriptions

boolean

在 `include_images` 為 `true` 時，為圖片加入描述。預設 `false`。

default: false

include_favicon

boolean

是否在每個結果中包含 favicon URL。預設 `false`。

default: false

include_domains

string[]

限定搜尋結果來自指定網域，最多 300 個。預設為空陣列。

default: []; maximum 300 items

exclude_domains

string[]

排除指定網域的搜尋結果，最多 150 個。預設為空陣列。

default: []; maximum 150 items

include_domains_mode

string

控制 `include_domains` 的套用方式。`restrict` 僅限列出的網域；`prefer` 優先列出的網域但仍可回傳其他網域。需要設定 `include_domains`，否則回傳 400。預設未設定。

default: null; requires include_domains

restrictprefer

country

string

提升指定國家的結果排名。僅在 `topic` 為 `general` 時可用；預設未設定。

default: null; only when topic is general

afghanistanalbaniaalgeriaandorraangolaargentinaarmeniaaustraliaaustriaazerbaijanbahamasbahrainbangladeshbarbadosbelarusbelgiumbelizebeninbhutanboliviabosnia and herzegovinabotswanabrazilbruneibulgariaburkina fasoburundicambodiacamerooncanadacape verdecentral african republicchadchilechinacolombiacomoroscongocosta ricacroatiacubacyprusczech republicdenmarkdjiboutidominican republicecuadoregyptel salvadorequatorial guineaeritreaestoniaethiopiafijifinlandfrancegabongambiageorgiagermanyghanagreeceguatemalaguineahaitihondurashungaryicelandindiaindonesiairaniraqirelandisraelitalyjamaicajapanjordankazakhstankenyakuwaitkyrgyzstanlatvialebanonlesotholiberialibyaliechtensteinlithuanialuxembourgmadagascarmalawimalaysiamaldivesmalimaltamauritaniamauritiusmexicomoldovamonacomongoliamontenegromoroccomozambiquemyanmarnamibianepalnetherlandsnew zealandnicaraguanigernigerianorth koreanorth macedonianorwayomanpakistanpanamapapua new guineaparaguayperuphilippinespolandportugalqatarromaniarussiarwandasaudi arabiasenegalserbiasingaporeslovakiasloveniasomaliasouth africasouth koreasouth sudanspainsri lankasudanswedenswitzerlandsyriataiwantajikistantanzaniathailandtogotrinidad and tobagotunisiaturkeyturkmenistanugandaukraineunited arab emiratesunited kingdomunited statesuruguayuzbekistanvenezuelavietnamyemenzambiazimbabwe

language

string

提升指定語言的結果排名。接受 ISO 639-1 代碼或英文語言名稱；預設未設定。

default: null

Example: en

filter_by_language

boolean

嚴格排除不符合 `language` 的結果。需要設定 `language`，否則回傳 400。預設 `false`。

default: false; requires language

auto_parameters

boolean

依查詢意圖自動設定搜尋參數。明確指定的值優先；`include_answer`、`include_raw_content`、`max_results` 必須手動指定。每次額外收費 2 credits。預設 `false`。

default: false; costs 2 credits

exact_match

boolean

只回傳包含查詢中引號片語的結果，避免同義詞或語意變體。預設 `false`。

default: false

include_usage

boolean

是否在回應中包含 credit 用量。預設 `false`。

default: false

safe_search

boolean

過濾成人或不安全內容。預設 `false`；`fast` 與 `ultra-fast` 不支援。

default: false; unsupported for fast and ultra-fast

api_key

string

可選的 JSON body 認證欄位。若沒有 Bearer header，可使用 BazaarLink API key；認證後會從驗證與轉發 body 移除。

days

integer

SDK 相容欄位 `days`。接受此欄位；依計畫可傳遞給相容層或忽略，不是 frozen OpenAPI 的欄位。

max_hours

integer

SDK 相容欄位 `max_hours`。接受此欄位；依計畫可傳遞給相容層或忽略，不是 frozen OpenAPI 的欄位。

fetch_timeout

number

SDK 相容欄位 `fetch_timeout`。接受此欄位；依計畫可傳遞給相容層或忽略，不是 frozen OpenAPI 的欄位。

cache_fallback

boolean

SDK 相容欄位 `cache_fallback`。接受此欄位；依計畫可傳遞給相容層或忽略，不是 frozen OpenAPI 的欄位。

timeout

number

SDK 相容的 timeout 欄位。接受此欄位；搜尋使用服務端 timeout，未知或不支援的欄位會被忽略。

POST /v1/search

1
2
3
4
5
6
7
8
9
10
curl https://api.bazaarlink.ai/v1/search \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest news on open-source language models",
    "search_depth": "basic",
    "max_results": 5,
    "topic": "news",
    "time_range": "week"
  }'

回應範例

成功回應包含 `query`、可選 `answer`、頂層 `images`、`results`（每項含 `title`、`url`、`content`、`score`，以及可選 `raw_content`、`published_date`、`favicon`、`images`、`id`）、可選 `auto_parameters`、`response_time`、`usage`（`credits` 與 BazaarLink 額外提供的 `cost`）和 `request_id`。`usage.cost` 是本次向客戶收取的 USD 價格，不是 COGS；`request_id` 是 BazaarLink 自己產生、可提供給客服的 ID。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "query": "Who is Leo Messi?",
  "answer": "Lionel Messi is an Argentine footballer.",
  "images": [
    {
      "url": "https://example.com/messi.jpg",
      "description": "Lionel Messi"
    }
  ],
  "results": [
    {
      "title": "Lionel Messi Facts | Britannica",
      "url": "https://www.britannica.com/facts/Lionel-Messi",
      "content": "Lionel Messi is an Argentine footballer.",
      "score": 0.81025416,
      "raw_content": null,
      "published_date": "Tue, 11 Mar 2025 17:00:00 GMT",
      "favicon": "https://britannica.com/favicon.png",
      "images": [
        {
          "url": "https://example.com/messi.jpg",
          "description": "Lionel Messi"
        }
      ],
      "id": "a3f9c2-04"
    }
  ],
  "auto_parameters": {
    "topic": "general",
    "search_depth": "basic"
  },
  "response_time": 1.67,
  "usage": {
    "credits": 1,
    "cost": "<customer_price_usd>"
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}