官方 SDK
使用官方 TypeScript 和 Python 客户端，获得类型化请求、错误类型、重试、批量请求和深度抓取轮询。
对于需要反复调用 Search1API 的应用代码，官方 SDK 是最快捷的方式。它们覆盖公开 OpenAPI 契约中的所有端点，并提供符合各语言习惯的配置、类型化响应、错误类、安全重试和深度抓取轮询。
当 AI 客户端需要把 Search1API 作为工具调用时，请使用 MCP。当由你自己的 TypeScript 或 Python 应用发起调用时，请使用 SDK。对于 AI SDK 智能体，请使用 Search1API 工具包，直接将搜索、新闻和网页读取添加到智能体的工具集中。
TypeScript
npm install @search1api/clientimport { 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);
}TypeScript 包支持 Node.js 18+，以及其他提供符合标准的 fetch 实现的运行时。
在 GitHub 上查看 TypeScript SDK 源码。
Python
pip install search1apifrom search1api import Search1API
client = Search1API() # 读取 SEARCH1API_API_KEY
response = client.search(
"latest AI agent frameworks",
max_results=10,
crawl_results=3,
)
for result in response["results"]:
print(result["title"], result["link"])异步客户端提供相同的操作：
from search1api import AsyncSearch1API
async with AsyncSearch1API() as client:
response = await client.search("latest AI agent frameworks")智能搜索（Ask）
ask 将自然语言请求发送到 POST /ask，由 Search1API 选择引擎和时间范围。它最多返回 10 条按相关性排序的结果，intent 会说明实际搜索了什么。每个完成的请求消耗 5 积分，ask 的默认超时时间为 45 秒。
const answer = await client.ask(
'What are developers saying about Bun 1.3 this month?'
);
console.log(answer.intent.sources, answer.intent.time_range);
for (const result of answer.results) {
console.log(result.relevance, result.source, result.title, result.link);
}answer = client.ask("What are developers saying about Bun 1.3 this month?")
print(answer["intent"]["sources"], answer["intent"]["time_range"])
for result in answer["results"]:
print(result["relevance"], result["source"], result["title"], result["link"])如果你已经明确要用哪个引擎和关键词，请使用 search。
二进制截图响应
截图 API 返回的是图片字节，而不是 JSON 对象。两个 SDK 都会在二进制内容之外保留响应的内容类型和请求 ID。
import { writeFile } from 'node:fs/promises';
const screenshot = await client.screenshot('https://example.com', {
format: 'png',
fullPage: true,
});
await writeFile('screenshot.png', screenshot.data);
console.log(screenshot.contentType, screenshot.requestId);from pathlib import Path
screenshot = client.screenshot(
"https://example.com",
format="png",
full_page=True,
)
Path("screenshot.png").write_bytes(screenshot["data"])
print(screenshot["content_type"], screenshot.get("request_id"))无需手写轮询的深度抓取
两个 SDK 都提供一个便捷方法，用于启动任务并等待其完成。
const result = await client.deepcrawl('https://example.com', { type: 'all' });
console.log(result.zipUrl);result = client.deepcrawl("https://example.com", type="all")
print(result["zipUrl"])如果你的应用需要持久化保存任务 ID，请分别使用启动、状态查询和等待方法。
错误、重试与超时
SDK 为以下情况提供了独立的错误类型：认证（401）、支付或积分（402）、参数校验（400/422）、资源不存在（404）、速率限制（429）以及服务器故障。错误对象上仍可获取状态码和解析后的响应体。
请求默认使用 30 秒超时，并对 429 和临时性 5xx 响应重试两次。认证、支付和参数校验错误永远不会重试。启动深度抓取任务也不会自动重试，因为响应丢失时重试可能会创建并扣费一个重复任务；feedback 同样不会重试，因为重试可能会提交重复的报告。如果你的工作负载需要不同的策略，可以在客户端上配置这些默认值。
API 覆盖范围
官方客户端支持 search 和 news（单个及批量）、ask、crawl（单个及批量）、Screenshot、sitemap、trending、extract、deepcrawl、feedback、usage 和 health。TypeScript 包还导出了生成的 OpenAPI 类型，供需要精确传输层（wire-level）契约的应用使用。