# 官方 SDK

> 使用官方 TypeScript 和 Python 客户端，获得类型化请求、错误类型、重试、批量请求和深度抓取轮询。

Canonical URL: https://s1.dev/zh/docs/integrations/sdks

对于需要反复调用 Search1API 的应用代码，官方 SDK 是最快捷的方式。它们覆盖公开 OpenAPI 契约中的所有端点，并提供符合各语言习惯的配置、类型化响应、错误类、安全重试和深度抓取轮询。

当 AI 客户端需要把 Search1API 作为工具调用时，请使用 [MCP](https://s1.dev/zh/docs/integrations/mcp)。当由你自己的 TypeScript 或 Python 应用发起调用时，请使用 SDK。对于 AI SDK 智能体，请使用 [Search1API 工具包](https://s1.dev/zh/docs/integrations/vercel-ai-sdk)，直接将搜索、新闻和网页读取添加到智能体的工具集中。

## TypeScript

```bash
npm install @search1api/client
```

```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);
}
```

TypeScript 包支持 Node.js 18+，以及其他提供符合标准的 `fetch` 实现的运行时。

[在 GitHub 上查看 TypeScript SDK 源码](https://github.com/superagents-lab/search1api-js)。

## Python

```bash
pip install search1api
```

```python
from 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"])
```

异步客户端提供相同的操作：

```python
from search1api import AsyncSearch1API

async with AsyncSearch1API() as client:
    response = await client.search("latest AI agent frameworks")
```

[在 GitHub 上查看 Python SDK 源码](https://github.com/superagents-lab/search1api-python)。

## 智能搜索（Ask）

`ask` 将自然语言请求发送到 [`POST /ask`](https://s1.dev/zh/docs/basic/ask)，由 Search1API 选择引擎和时间范围。它最多返回 10 条按相关性排序的结果，`intent` 会说明实际搜索了什么。每个完成的请求消耗 5 积分，`ask` 的默认超时时间为 45 秒。

```ts
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);
}
```

```python
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。

```ts
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);
```

```python
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 都提供一个便捷方法，用于启动任务并等待其完成。

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

```python
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）契约的应用使用。