Tavily Search API 文档

• API 接口
  • 1. Search 接口
  • 2. Extract 接口
• Java 客户端封装
  • TavilyClient.java
  • TavilySearchRequest.java
  • TavilySearchResponse.java
  • TavilySearchResult.java
  • TavilyExtractRequest.java
  • TavilyExtractResponse.java
  • TavilyExtractResult.java
• 调用示例
  • TavilyClientTest.java
• 总结

Tavily Search API 是专为 AI 智能体（例如大型语言模型，LLM）设计的搜索引擎。本文档将详细介绍该 API 的使用方式，包括搜索（search）和内容抽取（extract）接口，并提供基于 Java 的客户端封装示例及调用示例。

---

API 接口

1. Search 接口

该接口用于搜索指定的关键词，支持多种参数配置，如搜索深度、返回结果条数、是否包含答案等。以下为接口调用示例及返回示例。

请求示例

使用 curl 命令发送 POST 请求：

curl --request POST \
  --url https://api.tavily.com/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "who is Leo Messi?",
  "topic": "general",
  "search_depth": "basic",
  "chunks_per_source": 3,
  "max_results": 1,
  "time_range": null,
  "days": 3,
  "include_answer": true,
  "include_raw_content": false,
  "include_images": false,
  "include_image_descriptions": false,
  "include_domains": [],
  "exclude_domains": []
}'

返回示例

以下为 API 返回的 JSON 格式数据示例：

{
  "query": "Who is Leo Messi?",
  "answer": "Lionel Messi, born in 1987, is an Argentine footballer widely regarded as one of the greatest players of his generation. He spent the majority of his career playing for FC Barcelona, where he won numerous domestic league titles and UEFA Champions League titles. Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability. He has won multiple FIFA Ballon d'Or awards, numerous La Liga titles with Barcelona, and holds the record for most goals scored in a calendar year. In 2014, he led Argentina to the World Cup final, and in 2015, he helped Barcelona capture another treble. Despite turning 36 in June, Messi remains highly influential in the sport.",
  "images": [],
  "results": [
    {
      "title": "Lionel Messi Facts | Britannica",
      "url": "https://www.britannica.com/facts/Lionel-Messi",
      "content": "Lionel Messi, an Argentine footballer, is widely regarded as one of the greatest football players of his generation. Born in 1987, Messi spent the majority of his career playing for Barcelona, where he won numerous domestic league titles and UEFA Champions League titles. Messi is known for his exceptional dribbling skills, vision, and goal",
      "score": 0.81025416,
      "raw_content": null
    }
  ],
  "response_time": "1.67"
}

---

2. Extract 接口

该接口用于对指定 URL 的页面内容进行抽取，支持指定抽取深度以及是否需要抽取图片。下面为调用示例及返回示例。

请求示例

使用 curl 命令发送 POST 请求：

curl --request POST \
  --url https://api.tavily.com/extract \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "urls": "https://en.wikipedia.org/wiki/Artificial_intelligence",
  "include_images": false,
  "extract_depth": "basic"
}'

返回示例

返回数据中包含抽取结果列表、抽取失败的 URL 列表及响应耗时信息：

{
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
      "raw_content": "\"Jump to content\\nMain menu\\nSearch\\nAppearance\\nDonate\\nCreate account\\nLog in\\nPersonal tools\\n        Photograph your local culture, help Wikipedia and win!\\nToggle the table of contents\\nArtificial intelligence\\n161 languages\\nArticle\\nTalk\\nRead\\nView source\\nView history\\nTools\\nFrom Wikipedia, the free encyclopedia\\n\\\"AI\\\" redirects here. For other uses, see AI (disambiguation) and Artificial intelligence (disambiguation).\\nPart of a series on\\nArtificial intelligence (AI)\\nshow\\nMajor goals\\nshow\\nApproaches\\nshow\\nApplications\\nshow\\nPhilosophy\\nshow\\nHistory\\nshow\\nGlossary\\nvte\\nArtificial intelligence (AI), in its broadest sense, is intelligence exhibited by machines, particularly computer systems. It is a field of research in computer science that develops and studies methods and software that enable machines to perceive their environment and use learning and intelligence to take actions that maximize their chances of achieving defined goals.[1] Such machines may be called AIs.\\nHigh-profile applications of AI include advanced web search engines (e.g., Google Search); recommendation systems (used by YouTube, Amazon, and Netflix); virtual assistants (e.g., Google Assistant, Siri, and Alexa); autonomous vehicles (e.g., Waymo); generative and creative tools (e.g., ChatGPT and AI art); and superhuman play and analysis in strategy games (e.g., chess and Go)...................",
      "images": []
    }
  ],
  "failed_results": [],
  "response_time": 0.02
}

---

Java 客户端封装

为方便 Java 开发者调用 Tavily Search API，提供了一个完整的 Java 客户端封装实现。以下代码均未做删改，直接复制即可使用。

TavilyClient.java

package com.litongjava.tavily;

import com.litongjava.model.http.response.ResponseVo;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.http.HttpUtils;
import com.litongjava.tio.utils.json.JsonUtils;

public class TavilyClient {

  public static final String TAVILY_API_BASE = "https://api.tavily.com";

  /**
   * 发送请求，传入封装好的 SearchRequest 对象
   *
   * @param request 请求参数对象
   * @return 响应对象 ResponseVo
   */
  public static TavilySearchResponse search(TavilySearchRequest request) {
    String requestJson = JsonUtils.toSkipNullJson(request);
    String apiBase = EnvUtils.getStr("TAVILY_API_BASE", TAVILY_API_BASE);
    String url = apiBase + "/search";
    String token = EnvUtils.getStr("TAVILY_API_TOKEN");
    ResponseVo responseVo = HttpUtils.postJson(url, token, requestJson);
    int code = responseVo.getCode();
    String bodyString = responseVo.getBodyString();
    if (responseVo.isOk()) {

    } else {
      throw new RuntimeException("request:" + requestJson + " response code:" + code + " response body:" + bodyString);
    }

    return JsonUtils.parse(bodyString, TavilySearchResponse.class);
  }

  /**
   * 使用默认参数封装 SearchRequest 对象，并发送请求
   *
   * @param query 查询关键字
   * @return 响应对象 ResponseVo
   */
  public static TavilySearchResponse search(String query) {
    // 使用 Builder 构建 SearchRequest 对象
    TavilySearchRequest request = TavilySearchRequest.builder().query(query).topic("general").search_depth("basic")
        //
        .chunks_perSource(3).max_results(10).include_answer(false).include_raw_content(true)
        //
        .include_images(false).include_image_descriptions(false).build();
    return search(request);
  }

  /**
   * 发送 extract 请求，传入封装好的 TavilyExtractRequest 对象
   *
   * @param request 请求参数对象
   * @return 响应对象 TavilyExtractResponse
   */
  public static TavilyExtractResponse extract(TavilyExtractRequest request) {
    String requestJson = JsonUtils.toJson(request);
    String apiBase = EnvUtils.getStr("TAVILY_API_BASE", TAVILY_API_BASE);
    String url = apiBase + "/extract";
    String token = EnvUtils.getStr("TAVILY_API_TOKEN");
    ResponseVo responseVo = HttpUtils.postJson(url, token, requestJson);
    int code = responseVo.getCode();
    String bodyString = responseVo.getBodyString();
    if (!responseVo.isOk()) {
      throw new RuntimeException("request:" + requestJson + " response code:" + code + " response body:" + bodyString);
    }
    return JsonUtils.parse(bodyString, TavilyExtractResponse.class);
  }

  /**
   * 使用默认参数封装 TavilyExtractRequest 对象，并发送 extract 请求
   *
   * @param url 待抽取内容的链接
   * @return 响应对象 TavilyExtractResponse
   */
  public static TavilyExtractResponse extract(String url) {
    TavilyExtractRequest request = TavilyExtractRequest.builder().urls(url).include_images(false)
        //
        .extract_depth("basic").build();
    return extract(request);
  }
}

TavilySearchRequest.java

package com.litongjava.tavily;

import java.util.List;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class TavilySearchRequest {
  private String query;

  private String topic;

  private String search_depth;

  private Integer chunks_perSource;

  private Integer max_results;

  private Object time_range;

  private Integer days;

  private Boolean include_answer;

  private Boolean include_raw_content;

  private Boolean include_images;

  private Boolean include_image_descriptions;

  private List<String> include_domains;

  private List<String> exclude_domains;
}

TavilySearchResponse.java

package com.litongjava.tavily;

import java.util.List;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TavilySearchResponse {
  private String query;
  private String answer;
  private List<String> images;
  private List<TavilySearchResult> results;
  private String response_time;
}

TavilySearchResult.java

package com.litongjava.tavily;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TavilySearchResult {
  private String title;
  private String url;
  private String content;
  private Double score;
  private String raw_content;
}

TavilyExtractRequest.java

package com.litongjava.tavily;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TavilyExtractRequest {
  /**
   * 待抽取内容的 URL，支持单个或多个（根据实际需求，多个 URL 可改为 List<String>）
   */
  private String urls;

  /**
   * 是否需要抽取图片
   */
  private Boolean include_images;

  /**
   * 抽取深度，如 "basic"、"full" 等
   */
  private String extract_depth;
}

TavilyExtractResponse.java

package com.litongjava.tavily;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TavilyExtractResponse {
  /**
   * 成功抽取结果列表
   */
  private List<TavilyExtractResult> results;

  /**
   * 抽取失败的 URL 列表
   */
  private List<String> failed_results;

  /**
   * 响应耗时（单位秒）
   */
  private Double response_time;
}

TavilyExtractResult.java

package com.litongjava.tavily;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TavilyExtractResult {
  /**
   * 内容来源 URL
   */
  private String url;

  /**
   * 原始抽取内容
   */
  private String raw_content;

  /**
   * 图片列表
   */
  private List<String> images;
}

---

调用示例

下面是一个基于 JUnit 的调用示例，演示如何使用封装好的 Java 客户端进行 search 请求。

TavilyClientTest.java

package com.litongjava.client;

import org.junit.Test;

import com.litongjava.tavily.TavilyClient;
import com.litongjava.tavily.TavilySearchResponse;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.json.JsonUtils;

public class TavilyClientTest {

  @Test
  public void testSearch() {
    EnvUtils.load();
    TavilySearchResponse searchReponse = TavilyClient.search("什么是tio-boot");
    System.out.println(JsonUtils.toJson(searchReponse));
  }
}

如果需要登录 Extract 即可也无能为力

{
  "results": [],
  "failed_results": [
    {
      "url": "https://www.technewsworld.com/story/low-earth-orbit-networks-pushing-geostationary-giants-to-innovate-179658.html",
      "error": "Access denied: Unable to retrieve content from the specified URL"
    }
  ],
  "response_time": 0.48
}

---

总结

本文档详细介绍了 Tavily Search API 的两大核心接口（search 和 extract）的使用方法，并提供了完整的 Java 客户端封装实现。开发者可根据文档内容快速集成并使用该 API，以便在 AI 智能体（如大型语言模型）的场景中实现高效搜索和内容抽取。