TypeScript SDK

给 Node.js 和 TypeScript 用的网页搜索 API

官方 TypeScript 客户端用类型化响应覆盖公开 API 的全部端点——访问一个不存在的字段是编译错误，而不是上线后的意外。认证、超时、重试和 deepcrawl 轮询都由它接管。

安装 — bash
npm install @search1api/client
export SEARCH1API_API_KEY="your-api-key"
客户端替你处理什么

按公开契约做了类型定义，认证、重试和 deepcrawl 轮询也都已经写好。

1
端到端类型化

请求和响应都按公开 OpenAPI 契约做了类型定义。

2
可以 catch 的错误类

认证、积分、参数校验、限流、服务端故障各有独立错误类。

3
不止跑在 Node 上

Node.js 18 及以上，以及任何具备标准 fetch 的运行时。

覆盖

search / news / crawl / screenshot / extract / deepcrawl

在 Node.js 里搜索网页

网页搜索 API 返回的是代码能直接读的结构化结果——每条包含标题、链接和正文——而不是一个还要你解析的 HTML 页面。在 TypeScript 里，这个结构的价值不止于方便：响应形状是有类型的，字段写错在发布前就被编译器拦住。Search1API 通过一个端点、覆盖十几个来源返回 JSON，还能把靠前结果的完整正文放进同一个响应。

客户端替你处理的事

端到端类型化

请求和响应都按公开 OpenAPI 契约做了类型定义，编辑器知道有哪些选项名和结果字段。

一个客户端覆盖所有端点

搜索、新闻、抓取、截图、站点链接、热榜、结构化提取、deepcrawl 都是同一个实例上的方法。

可以 catch 的错误类

认证、积分、参数校验、not found、限流、服务端故障各有独立的错误类，都带着状态码和解析后的响应体。

只在安全的地方重试

30 秒超时，429 和临时性 5xx 自动重试两次。认证、支付、参数校验错误不重试，deepcrawl 任务的启动也不自动重试。

不止跑在 Node 上

支持 Node.js 18 及以上，以及任何具备标准 fetch 的运行时，所以同一个客户端在 edge 和 worker 环境里也能用。

deepcrawl 不用自己写轮询

一个 await 启动任务并在完成时 resolve。如果任务 ID 需要持久化，也有独立的 start、status、wait 方法。

快速开始

在控制台创建 key，传给构造函数，然后就能搜。传入 crawlResults，靠前的结果会在同一次调用里连整页正文一起返回。

search.ts — ts
import { Search1API } from '@search1api/client';
​
const client = new Search1API({
  apiKey: process.env.SEARCH1API_API_KEY,
});
​
const response = await client.search('latest AI agent frameworks', {
  maxResults: 10,
  crawlResults: 3,
});
​
for (const result of response.results) {
  console.log(result.title, result.link);
}

不用手写轮询的 deepcrawl

抓取整个站点通常意味着：启动任务、轮询状态、自己写等待逻辑。客户端用一个 await 就做完，并以完成后的归档 URL resolve。

deepcrawl.ts — ts
const result = await client.deepcrawl('https://example.com', {
  type: 'all',
});
​
console.log(result.zipUrl);

覆盖哪些端点

不管从哪条路调用，消耗的积分都一样：搜索或新闻各 1 积分，每成功取回一个页面再加 1 积分。

搜索 API
新闻 API
爬虫 API
数据提取 API

大家用它做什么

用实时网页证据作答并标明来源的 Next.js route handler。

为 AI SDK 或其他框架把客户端包一层做成的 agent 工具。

盯住某个话题、把简报发到 Slack 的后台任务。

拿到域名后去读真实页面、而不是靠猜的线索补全。

不能引入 Node 专属依赖、但需要搜索能力的 edge function。

常见问题

在 Node.js 里怎么搜索网页？

装上 @search1api/client，用你的 API key 构造它，然后 await client.search("你的查询")。返回是一个包含 results 数组的类型化对象，每条带标题、链接和正文。不用解析 HTML，也不用爬。

Node.js 之外能用吗？

能。它支持 Node.js 18 及以上，以及任何提供标准 fetch 实现的运行时，包括 edge 和 worker 环境。

碰到限流会怎样？

429 会自动重试两次，临时性 5xx 同理。认证、支付、参数校验类错误会直接 reject 而不重试——重试这些也解决不了问题。

可以用哪些搜索引擎？

Google、Bing、DuckDuckGo、Yahoo、GitHub、arXiv、Reddit、X、YouTube、Wikipedia、IMDb、微信公众号、哔哩哔哩、百度、360、夸克。在请求里用 searchService 指定即可。

有免费额度吗？

新账户免费赠送 100 积分且无需绑卡，相当于 100 次搜索。搜索或新闻各 1 积分，每成功取回一个页面再加 1 积分。

了解更多

Python 搜索 API
MCP 服务器
集成
定价

开始在 Node.js 里搜索

装一次，100 个免费积分够你试出来，不用绑卡。