Tavily 搜索

Tavily 是专为 AI 设计的搜索引擎，三方服务模块下提供 5 个工具，覆盖「搜索 / 抽取 / 爬取 / 站点地图 / 深度研究」全链路。

服务 slug：tavily_search
调用协议、鉴权、错误处理详见：调用说明
工具列表实时获取：GET /v1/openapi/third-party-service/tavily_search/tools

TIP

本页字段说明同步自平台插件 schema 与 tavily_search 执行器实现，调用方应以工具列表接口返回为准。文档示例仅作演示，请勿在客户端硬编码 工具或字段清单。

工具一览

工具 slug	名称	用途	典型耗时
`tavily_search`	Tavily 搜索	关键词搜索 + AI 摘要	< 5 s
`tavily_extract`	Tavily 网页提取	批量抓取 URL 正文	< 10 s
`tavily_crawl`	Tavily 站点爬取	按深度爬取子站点	< 30 s
`tavily_map`	Tavily 站点地图	仅枚举 URL，不抓正文	< 30 s
`tavily_research`	Tavily 深度研究	多轮调研生成报告，异步轮询	1–3 min

通用调用形式（所有工具相同）：

POST /v1/openapi/third-party-service/tavily_search/:tool/invoke
{
  "inputs": { ... }
}

tavily_search 搜索

接口说明

使用 Tavily 搜索引擎执行智能搜索，返回与查询最相关的网页结果和摘要。专为 AI 优化，支持多种搜索深度和主题分类。

工具 slug：tavily_search
完整路径：POST /v1/openapi/third-party-service/tavily_search/tavily_search/invoke

入参（`inputs`）

字段	类型	必填	默认	说明
`query`	string	是	-	搜索关键词
`max_results`	integer	否	5	返回结果数量（1–20）
`search_depth`	string	否	`basic`	`basic`(标准) / `advanced`(深度，2 倍积分) / `fast`(快速) / `ultra-fast`(极速)
`topic`	string	否	`general`	`general` / `news` / `finance`；设置 `country` 时会强制为 `general`
`time_range`	string	否	-	`day` / `week` / `month` / `year`
`start_date`	string	否	-	`YYYY-MM-DD` 之后的结果
`end_date`	string	否	-	`YYYY-MM-DD` 之前的结果
`country`	string	否	-	按国家英文全名加权（如 `China`、`United States`），仅 `topic=general` 时生效
`include_answer`	boolean	否	`false`	是否在结果中包含 AI 生成的摘要
`include_images`	boolean	否	`false`	是否返回与查询相关的图片
`include_image_descriptions`	boolean	否	`false`	返回的图片是否附带描述
`include_raw_content`	boolean	否	`false`	每条结果是否附原始正文清洗后纯文本
`include_favicon`	boolean	否	`false`	是否返回站点 favicon
`exact_match`	boolean	否	`false`	仅返回包含 `query` 中完整短语的结果
`include_domains`	string	否	-	域名白名单，多个用英文逗号分隔
`exclude_domains`	string	否	-	域名黑名单，多个用英文逗号分隔

出参（`output`）字段

字段	类型	说明
`query`	string	原始搜索关键词
`answer`	string	AI 生成的摘要（`include_answer=true` 时返回）
`response_time`	number	接口处理耗时（秒）
`results[]`	array	搜索结果数组
`results[].title`	string	页面标题
`results[].url`	string	页面 URL
`results[].content`	string	页面摘要
`results[].score`	number	相关性评分（0–1）
`results[].raw_content`	string	原始正文清洗结果（`include_raw_content=true` 时返回）
`results[].published_date`	string	发布日期（部分新闻类结果返回）
`results[].favicon`	string	站点 favicon URL（`include_favicon=true` 时返回）
`images[]`	array	相关图片（`include_images=true` 时返回），含 `url` / `description`

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_search/invoke' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "query": "OpenAI o1",
      "max_results": 2,
      "search_depth": "advanced",
      "include_answer": true
    }
  }'

成功响应示例

json

{
  "code": 200,
  "data": {
    "service": "tavily_search",
    "tool": "tavily_search",
    "output": {
      "query": "OpenAI o1",
      "answer": "OpenAI o1 是 OpenAI 在 2024 年发布的推理增强型模型……",
      "response_time": 0.77,
      "results": [
        {
          "title": "OpenAI o1 - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/OpenAI_o1",
          "content": "OpenAI o1 is a generative pre-trained transformer (GPT)...",
          "score": 0.954
        }
      ]
    }
  },
  "message": "success",
  "trace_id": "ece1bfa480da3a5bb346cf83cfc29454"
}

tavily_extract 网页提取

接口说明

从指定 URL 提取网页正文内容，支持多个 URL 批量提取，返回清洗后的结构化文本。

工具 slug：tavily_extract
完整路径：POST /v1/openapi/third-party-service/tavily_search/tavily_extract/invoke

入参（`inputs`）

字段	类型	必填	默认	说明
`urls`	string \| string[]	是	-	要提取内容的网页 URL；可为单个字符串或字符串数组，单字符串多个 URL 时用英文逗号分隔
`extract_depth`	string	否	`basic`	`basic`(标准) / `advanced`(深度，含表格等嵌入内容)
`format`	string	否	`markdown`	`markdown` / `text`
`include_images`	boolean	否	`false`	是否返回页面中的图片信息
`include_favicon`	boolean	否	`false`	是否返回站点 favicon
`query`	string	否	-	按此查询对正文片段做相关性重排（`advanced` 模式更明显）

出参（`output`）字段

字段	类型	说明
`results[]`	array	成功提取的页面
`results[].url`	string	页面 URL
`results[].raw_content`	string	提取的正文（按 `format` 渲染）
`results[].favicon`	string	站点 favicon URL
`failed_results[]`	array	提取失败的页面
`failed_results[].url`	string	失败的 URL
`failed_results[].error`	string	失败原因
`response_time`	number	接口处理耗时（秒）

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_extract/invoke' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "urls": ["https://en.wikipedia.org/wiki/OpenAI_o1"],
      "extract_depth": "advanced",
      "format": "markdown"
    }
  }'

tavily_crawl 站点爬取

接口说明

从指定 URL 开始爬取整个站点，自动发现并提取子页面内容。支持设置爬取深度、广度和自然语言指令进行智能筛选。

工具 slug：tavily_crawl
完整路径：POST /v1/openapi/third-party-service/tavily_search/tavily_crawl/invoke

入参（`inputs`）

字段	类型	必填	默认	说明
`url`	string	是	-	开始爬取的起始 URL
`max_depth`	integer	否	1	爬取最大深度（1–5）
`max_breadth`	integer	否	20	每层跟踪的最大链接数（1–500）
`limit`	integer	否	50	总共爬取的最大页面数
`instructions`	string	否	-	自然语言爬取指令，用于智能筛选页面（使用后积分加倍）
`extract_depth`	string	否	`basic`	内容提取深度：`basic` / `advanced`
`format`	string	否	`markdown`	`markdown` / `text`
`include_favicon`	boolean	否	`false`	是否返回站点 favicon
`allow_external`	boolean	否	`true`	是否在结果中保留外站链接
`select_paths`	string	否	-	路径正则白名单，多个用英文逗号分隔（如 `/docs/.,/api/v1.`）
`select_domains`	string	否	-	域名正则白名单，多个用英文逗号分隔（如 `^docs\.example\.com$`）

出参（`output`）字段

字段	类型	说明
`base_url`	string	起始 URL
`results[]`	array	爬到的页面
`results[].url`	string	页面 URL
`results[].raw_content`	string	提取后的正文
`results[].favicon`	string	站点 favicon URL
`response_time`	number	接口处理耗时（秒）

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_crawl/invoke' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "url": "https://docs.example.com",
      "max_depth": 2,
      "limit": 20,
      "instructions": "查找所有关于 API 文档的页面"
    }
  }'

tavily_map 站点地图

接口说明

从指定 URL 出发遍历站点，生成完整的站点地图（仅返回 URL 列表，不提取内容）。适用于快速了解站点结构。

工具 slug：tavily_map
完整路径：POST /v1/openapi/third-party-service/tavily_search/tavily_map/invoke

入参（`inputs`）

字段	类型	必填	默认	说明
`url`	string	是	-	开始映射的起始 URL
`max_depth`	integer	否	1	映射最大深度（1–5）
`max_breadth`	integer	否	20	每层跟踪的最大链接数（1–500）
`limit`	integer	否	50	总共发现的最大链接数
`instructions`	string	否	-	自然语言指令，用于智能筛选链接（使用后积分加倍）
`allow_external`	boolean	否	`true`	是否在结果中保留外站链接
`select_paths`	string	否	-	路径正则白名单，多个用英文逗号分隔
`select_domains`	string	否	-	域名正则白名单，多个用英文逗号分隔

出参（`output`）字段

字段	类型	说明
`base_url`	string	起始 URL
`results[]`	array	发现的所有 URL 对象
`results[].url`	string	站点 URL
`response_time`	number	接口处理耗时（秒）

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_map/invoke' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "url": "https://docs.example.com",
      "max_depth": 2,
      "limit": 50
    }
  }'

tavily_research 深度研究

接口说明

对指定主题进行深度研究，自动执行多轮搜索、分析来源并生成详细的研究报告。适用于复杂问题的多角度调研，耗时较长（通常 1–3 分钟）。

工具 slug：tavily_research
完整路径：POST /v1/openapi/third-party-service/tavily_search/tavily_research/invoke

WARNING

平台内部采用「提交 + 轮询」实现，最长等待 5 分钟；超过则返回 research 任务等待超时。调用方应将客户端超时设置为 ≥ 5 分钟（建议 6 分钟），并对错误响应做兜底重试。

入参（`inputs`）

字段	类型	必填	默认	说明
`input`	string	是	-	要研究的主题或问题
`model`	string	否	`auto`	`mini`(快速精简) / `pro`(深度全面) / `auto`(自动选择)

出参（`output`）字段

字段	类型	说明
`request_id`	string	研究任务 ID（轮询时使用）
`status`	string	任务状态：`completed` / `pending` / `in_progress` / `failed`
`content`	string	研究报告正文（`status=completed` 时返回）
`sources[]`	array	参考来源
`sources[].title`	string	来源标题
`sources[].url`	string	来源 URL

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_research/invoke' \
  --max-time 360 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "input": "OpenAI o1 与 o3 推理能力对比",
      "model": "pro"
    }
  }'

凭证与额度

API Key：在控制台为 workspace 配置 Tavily API Key（以 tvly- 开头），未配置时调用返回 三方服务凭证未配置。
积分加倍：search_depth=advanced、tavily_crawl / tavily_map 的 instructions 字段使用后将按 2 倍积分计费。
常用错误：网络失败、Tavily 配额耗尽等会以 tavily API 请求失败: ... 或 tavily API 返回状态码 xxx: ... 形式回传到 message 字段，便于排查。

Tavily 搜索 ​

工具一览 ​

tavily_search 搜索 ​

接口说明 ​

入参（inputs） ​

出参（output）字段 ​

调用示例 ​

成功响应示例 ​

tavily_extract 网页提取 ​

接口说明 ​

入参（inputs） ​

出参（output）字段 ​

调用示例 ​

tavily_crawl 站点爬取 ​

接口说明 ​

入参（inputs） ​

出参（output）字段 ​

调用示例 ​

tavily_map 站点地图 ​

接口说明 ​

入参（inputs） ​

出参（output）字段 ​

调用示例 ​

tavily_research 深度研究 ​

接口说明 ​

入参（inputs） ​

出参（output）字段 ​

调用示例 ​

凭证与额度 ​

Tavily 搜索

工具一览

tavily_search 搜索

接口说明

入参（`inputs`）

出参（`output`）字段

调用示例

成功响应示例

tavily_extract 网页提取

接口说明

入参（`inputs`）

出参（`output`）字段

调用示例

tavily_crawl 站点爬取

接口说明

入参（`inputs`）

出参（`output`）字段

调用示例

tavily_map 站点地图

接口说明

入参（`inputs`）

出参（`output`）字段

调用示例

tavily_research 深度研究

接口说明

入参（`inputs`）

出参（`output`）字段

调用示例

凭证与额度