网络搜索

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；验证和转发前会移除。

days

integer

SDK 兼容字段 `days`。为兼容性接受；按计划可由兼容层传递或忽略，不属于 frozen OpenAPI schema。

max_hours

integer

SDK 兼容字段 `max_hours`。为兼容性接受；按计划可由兼容层传递或忽略，不属于 frozen OpenAPI schema。

fetch_timeout

number

SDK 兼容字段 `fetch_timeout`。为兼容性接受；按计划可由兼容层传递或忽略，不属于 frozen OpenAPI schema。

cache_fallback

boolean

SDK 兼容字段 `cache_fallback`。为兼容性接受；按计划可由兼容层传递或忽略，不属于 frozen OpenAPI schema。

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` 加上我们额外提供的 `cost`）和 `request_id`。`usage.cost` 是向客户收取的 USD 价格，不是 COGS；`request_id` 由 BazaarLink 生成。

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"
}