网页搜索与抓取

接口列表

接口	端点
网页搜索（Search）	POST /tools/search
网页抓取（Fetch）	POST /tools/fetch

端点均以接入地址为前缀。两个接口的请求与响应都是 JSON，不依赖 SDK，也不会调用模型。

鉴权

使用与对话接口相同的 API Key。请求头需包含：

Authorization: Bearer <你的飞鱼Token API Key>
Content-Type: application/json

Search 接口

请求

curl https://open.feiyutoken.com/v1/tools/search \
  -H "Authorization: Bearer <你的飞鱼Token API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "大模型 API 网关",
    "count": 5,
    "need_content": true
  }'

请求参数：

参数	类型	必填	说明
query	string	是	搜索词，1～128 个 Unicode 字符，不能全为空白。支持下方搜索语法。
count	integer	否	返回条数，1～50，默认 10。
ori_question	string	否	触发搜索的用户原始问题，1～128 个字符，用于帮助理解搜索意图；传 null 视为未提供。
localization	string	否	用于优先返回本地化搜索结果的 IP 地址，默认空字符串。
need_content	boolean	否	是否在 content 中返回网页正文。默认 false，此时 content 恒为空字符串。

搜索语法

query 中的搜索语法会原样传递给搜索服务。下表中的示例将操作符与搜索词组合使用；可以在一个 query 中组合多个操作符。

操作符	示例	说明
site:	大模型 site:github.com	将结果限制在指定站点。指定多个时用空格分隔并通过 OR 连接，例如 大模型 site:github.com OR site:huggingface.co。
-site:	大模型 -site:example.com	排除指定站点。指定多个时用空格分隔。
-	大模型 -广告	排除包含指定关键词的网页。指定多个时用空格分隔。
-"..."	大模型 -"release notes"	排除包含指定短语的网页。短语内可以包含空格，指定多个时用空格分隔。
"..."	大模型 "精确短语"	精确匹配指定短语。指定多个时用空格分隔。
lang:	大模型 lang:zh,en	将结果限制在指定语言。多种语言用逗号分隔，例如 lang:zh,en。
after:	大模型 after:2025 或 大模型 after:2025-01-01	将结果限制在指定日期之后发布的网页。
before:	大模型 before:2026 或 大模型 before:2026-06-01	将结果限制在指定日期之前发布的网页。

组合示例：

{
  "query": "大模型 API site:github.com OR site:huggingface.co lang:zh after:2025",
  "count": 10
}

响应

请求成功时返回 HTTP 200 与 results 数组；没有匹配结果时 results 为空数组，仍视为成功。

{
  "results": [
    {
      "rerank_score": 2.4,
      "title": "示例文章标题",
      "url": "https://example.com/article",
      "snippet": "与查询相关的一段短摘要，通常 100～200 字符。",
      "summary": "更长的一段摘要，通常 600～800 字符，适合直接交给模型阅读。",
      "content": "网页正文……",
      "site_name": "Example",
      "site_icon": "https://example.com/favicon.ico",
      "date": "2026-06-01T00:00:00+00:00",
      "authority": 3
    }
  ]
}

results 中每一项包含以下字段：

字段	类型	说明
rerank_score	number	排序分数，0～3 分，综合考虑相关性、权威性、时效性等维度，大于等于 1.5 分为优质结果。
title	string	标题。
url	string	结果链接。
snippet	string	短摘要，与 query 相关，通常为 100～200 字符，适用于前端展现。
summary	string	长摘要，与 query 相关，通常为 600～800 字符，适用于给模型阅读。
content	string	网页正文，need_content 为 false 或正文缺失时为空字符串。
site_name	string 或 null	站点名称，缺失时为 null。
site_icon	string 或 null	站点图标 URL，缺失时为 null。
date	string 或 null	发布时间，统一为 UTC 的 RFC 3339 格式，未知时为 null。
authority	integer	网页权威性，0～4（-1 表示未知），大于等于 3 为高权威结果。

Fetch 接口

请求

curl https://open.feiyutoken.com/v1/tools/fetch \
  -H "Authorization: Bearer <你的飞鱼Token API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article"
  }'

请求参数：

参数	类型	必填	说明
url	string	是	要抓取的网页地址，长度不超过 8192；必须为带 host 的 HTTP/HTTPS URL，且不能携带用户名或密码。

响应

请求成功时返回 HTTP 200，正文已经转换为 Markdown：

{
  "title": "Example article",
  "content": "# Example article\n\nArticle content."
}

字段	类型	说明
title	string	页面标题；缺失时为空字符串。
content	string	抓取后的 Markdown 正文。

content 为 Markdown 文本，可直接用于提示词或存入知识库。

抓取结果受目标站点的可用性与访问策略影响。需要登录的页面、被站点拦截的地址、没有可提取正文的页面，可能取不到内容；依赖 JavaScript 渲染的页面也不保证能抓全。

使用方式

• 对话补充实时信息：先调用 Search，将结果的 summary 加入 messages，再发起对话请求；需要细节时先调用 Fetch 获取 content。
• 作为 Agent 工具：在 tools 中定义对应函数，模型返回 tool_calls 后由代码调用这两个接口。写法与 Tool Calls 一致。
• RAG 检索：使用 Search 召回候选页面，使用 Fetch 获取正文，再按需接入创建嵌入与文档重排序。

错误处理

错误响应为 OpenAI 兼容格式，param 恒为 null：

{
  "error": {
    "message": "'count' must be between 1 and 50",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request_error"
  }
}

状态码	含义	处理建议
400	请求头或请求体不合法，包括 JSON 格式错误、字段值无效	修改请求后重试
401	API Key 缺失或无效	检查 Key 后重试
402	账号余额不足	充值后重试
403	Fetch 请求被安全策略拒绝	不要重试
404	Fetch 未能获取可用正文：URL 不可用、被站点拦截、目标站点返回错误、内容类型不支持，或页面没有可提取的正文	更换地址或放弃
408	读取请求体超时	可重试
413	请求体超过大小限制	缩小请求后重试
429	超过 Search 或 Fetch 的 QPS 限制	退避后重试
500	服务端内部错误	稍后重试
504	下游请求超时	稍后重试

Search 与 Fetch 均为只读请求。402 需先充值；408、429、5xx 可退避后重试；其余 4xx 在未修改请求的情况下不应重试。

计费

Search 和 Fetch 按请求次数计费，不按 Token 或返回结果条数计费：

API	计费单位	价格
Search	每 1,000 次成功请求	5 元
Fetch	每 1,000 次成功请求	5 元

只有返回 HTTP 200 且产生结果的请求才会计费（Search 的 results 必须非空，Fetch 必须返回网页正文）。请求失败、搜索无结果或超时不计费。count 只控制返回的结果条数，不影响单次请求的价格。

限速

对每个账号，Search 和 Fetch 分别独立限速，互不占用额度：

API	QPS 限制
Search	100
Fetch	25

QPS（每秒请求数）限制按账号粒度计算，与使用哪个 API Key 无关，并与模型并发限制相互独立。超过账号级 QPS 限制的请求会收到 HTTP 429。

除账号级限制外，Fetch 还对目标域名有 QPS 限制，超过该限制同样会收到 HTTP 429。

完整参数与响应字段见网页搜索接口与网页抓取接口。