Tavily（全球，LLM-optimized）

请求体与响应结构完全透传 Tavily 官方协议，完整参数（search_depth、topic、time_range、include_domains、include_answer、include_raw_content 等）请见 Tavily Search API Reference。

• 端点：POST /proxy/tavily/search
• 必填参数：query
• 常用参数：max_results、search_depth（basic / advanced）、topic（general / news / finance）、time_range、include_answer、include_raw_content、include_domains、exclude_domains

curl $TURING_BASE_URL/proxy/tavily/search \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2024",
    "max_results": 5
  }'

响应节选：

{
  "query": "latest AI developments 2024",
  "results": [
    {
      "title": "2024 Global Trends in AI - WEKA",
      "url": "https://www.weka.io/resources/analyst-report/2024-global-trends-in-ai/",
      "content": "Discover key AI trends in 2024…",
      "score": 0.7498395
    }
  ],
  "responseTime": 0.86,
  "requestId": "bb84e696-88cd-4b0f-b832-0aba925d312e"
}

Tavily Extract（网页正文提取）

从一批已知 URL 中提取干净正文，适合你已经有链接列表（自己爬到的候选页、用户粘贴的链接），需要拿去做 embedding / RAG。

• 端点：POST /proxy/tavily/extract
• 必填参数：urls（单个 URL 字符串或 URL 数组）
• 常用参数：query（让提取聚焦于与该查询相关的内容）、extract_depth（basic / advanced，advanced 计费翻倍）、format（markdown / text）、chunks_per_source、include_images、include_favicon、timeout

curl $TURING_BASE_URL/proxy/tavily/extract \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing"],
    "extract_depth": "advanced",
    "format": "markdown"
  }'

响应节选：

{
  "results": [
    {
      "url": "https://example.com/pricing",
      "raw_content": "# Pricing\n..."
    }
  ],
  "failed_results": []
}

提示

只按成功返回的 URL 计费，出现在 failed_results 里的链接不计费。计费公式：(成功 URL 数 / 5) × (1，basic 或 2，advanced) × $0.008。

Tavily Crawl（站内爬取）

从一个起始 URL 出发，按链接向外爬取并提取沿途每个页面的正文，适合你没有现成 URL 列表、只有一个入口页面，需要自动发现并抓取相关子页面。

• 端点：POST /proxy/tavily/crawl
• 必填参数：url（起始 URL）
• 常用参数：instructions（自然语言描述要找哪些页面，如 "find pricing pages"）、max_depth（跟随的链接深度）、max_breadth（每页最多跟随的链接数）、limit（爬取页面总数上限）、select_paths / select_domains（正则白名单）、exclude_paths / exclude_domains（正则黑名单）、allow_external（是否跟随站外链接）、extract_depth（对每个爬到的页面生效，语义同 Extract）

curl $TURING_BASE_URL/proxy/tavily/crawl \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "instructions": "find pricing pages",
    "max_depth": 2,
    "limit": 20
  }'

响应节选：

{
  "base_url": "https://example.com",
  "results": [
    { "url": "https://example.com/pricing", "raw_content": "..." },
    { "url": "https://example.com/plans", "raw_content": "..." }
  ]
}

提示

计费 = Map 费用 + Extract 费用，两者都按同一批成功页面数计算：map_cost(页面数) + extract_cost(页面数, extract_depth)。例如 20 个成功页面、extract_depth: "basic" 时为 (20/10 × $0.008) + (20/5 × $0.008) = $0.048。

Tavily Map（站点结构发现）

只发现站点的 URL 结构、不提取正文内容，适合你只是想知道"这个站点下有哪些页面"，之后再按需挑选页面调用 Extract。

• 端点：POST /proxy/tavily/map
• 必填参数：url（起始 URL）
• 常用参数：instructions（自然语言描述要包含哪些页面，设置后计费翻倍）、max_depth、max_breadth、limit（语义同 Crawl）、select_paths / select_domains（正则白名单）、exclude_paths / exclude_domains（正则黑名单）、allow_external

curl $TURING_BASE_URL/proxy/tavily/map \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_depth": 3,
    "select_paths": ["/docs/.*"]
  }'

响应节选：

{
  "base_url": "https://example.com",
  "results": [
    "https://example.com/docs/quickstart",
    "https://example.com/docs/api-reference"
  ]
}

提示

按成功发现的页面数计费，不提取正文，是三者中最便宜的：(成功页面数 / 10) × (1，未设置 instructions 或 2，设置了 instructions) × $0.008。

限流与错误

Extract / Crawl / Map 与 /proxy/tavily/search 共用同一套按 Key / 按团队的限流策略——超出配额或 RPM 限制的请求会在消耗 Tavily 额度之前被直接拒绝。Tavily 返回的错误会原样映射为对应的 HTTP 状态码（400/422 参数错误、401 凭证失效、408/504 超时、429 限流、5xx 上游故障），不会被统一包装成 500。