# Tavily

> 只需更换 API 基础 URL 和密钥，即可通过 Search1API 使用 Tavily SDK 和基于 Tavily 的集成。

Canonical URL: https://s1.dev/zh/docs/compatibility/tavily

Search1API 兼容 Tavily 的 `POST /search` 和 `POST /extract`。将 Tavily 基础 URL 设置为：

```text
https://api.search1api.com/compat/tavily
```

与 Tavily SDK 的做法一样，使用 `Authorization: Bearer YOUR_API_KEY` 携带你的 Search1API 密钥进行认证。旧版客户端使用的请求体字段 `api_key` 同样可用。

## 配置客户端

<Tabs items={['Python', 'JavaScript', 'Open WebUI']}>

<Tab value="Python">

```python
from tavily import TavilyClient

client = TavilyClient(
    api_key="YOUR_API_KEY",
    api_base_url="https://api.search1api.com/compat/tavily",
)
response = client.search("hono cloudflare workers", max_results=5)
pages = client.extract(urls=["https://hono.dev/docs/"])
```

</Tab>

<Tab value="JavaScript">

```ts
import { tavily } from '@tavily/core';

const client = tavily({
  apiKey: process.env.SEARCH1API_KEY,
  apiBaseURL: 'https://api.search1api.com/compat/tavily',
});
const response = await client.search('hono cloudflare workers', { maxResults: 5 });
const pages = await client.extract(['https://hono.dev/docs/']);
```

</Tab>

<Tab value="Open WebUI">

选择 **tavily** 作为网页搜索引擎，将你的 Search1API 密钥填为 Tavily API 密钥，并设置：

```bash
TAVILY_API_BASE_URL="https://api.search1api.com/compat/tavily"
```

</Tab>

</Tabs>

## 搜索

| 字段 | 行为 |
| --- | --- |
| `query` | 必填。 |
| `max_results` | 默认 `10`，最多 `50`。 |
| `topic` | `news` 搜索新闻。`general` 和 `finance` 搜索网页。 |
| `time_range` | `day`、`week`、`month`、`year` 或 `d`、`w`、`m`、`y`。 |
| `days`, `start_date` | 转换为能覆盖该时间段的最短区间：天、周、月或年。 |
| `include_domains`, `exclude_domains` | 限定或排除站点。 |
| `include_raw_content` | 设为 `true`、`"markdown"` 或 `"text"` 时，读取每条结果的完整页面，以 Markdown 形式放入 `raw_content`。 |

`search_depth`、`chunks_per_source`、`include_answer`、`include_images`、`country`、`auto_parameters` 等选项会被接受但忽略。

响应包含 Tavily 的字段：`query`、`results`、`answer`、`images`、`follow_up_questions`、`response_time` 和 `request_id`。每条结果包含 `title`、`url`、`content`（搜索摘要）、`score`、`raw_content`，以及已知时提供的 `published_date`。

- `answer` 和 `follow_up_questions` 为 `null`，`images` 为空。
- `score` 由结果排名推算，第一条结果为 `1`，依次递减。
- 不返回 `usage`。

## 内容提取

`urls` 接受单个 URL，或最多 20 个 URL 的列表。每个页面以 `{ url, raw_content, images }` 的形式返回在 `results` 中，`raw_content` 为 Markdown。无法读取的页面以 `{ url, error }` 的形式出现在 `failed_results` 中，请求仍返回 `200`。`extract_depth`、`format`、`query` 和 `timeout` 会被忽略。

## 积分

| 请求 | 积分 |
| --- | --- |
| 搜索 | 1 |
| 带 `include_raw_content` 的搜索 | 1，每读取一个页面再加 1 |
| 内容提取 | 每读取一个页面 1 |

## 错误

错误返回 `{ "detail": { "error": "message" } }` 及相应状态码，Tavily SDK 会将其转换为自己的异常。只有当因密钥、积分或速率限制而一个页面都没有读取时，内容提取才会返回错误，而不是 `failed_results`。