Search1APIDocs

Vercel AI SDK

Give AI SDK agents web search, news, webpage reading, and agentic search with the official Search1API tools package.

For both Vercel integration options, including Vercel Connect, see the Vercel guide.

@search1api/ai-sdk exposes Search1API as ordinary AI SDK tools. Use it with generateText, streamText, or an agent and your preferred model provider. One package covers search across engines such as Google, Reddit, GitHub, and YouTube, plus crawl for reading the full page behind a result, so the agent can search, read, and cite without a separate scraping service. The package uses the official TypeScript SDK for API calls.

Install and configure

npm install @search1api/ai-sdk ai zod

Create a key in the dashboard, then set it in the server's environment:

export SEARCH1API_API_KEY="your-api-key"

The compatibility alias SEARCH1API_KEY is also accepted. An explicit apiKey takes precedence. Keep the key in server code.

AI SDK 5, 6, and 7 are supported with Zod 3.25.76+ or 4.1.8+. Use a Node.js version supported by your AI SDK release; AI SDK 7 requires Node.js 22+.

Search, read, and answer

This example uses Vercel AI Gateway, which needs its own AI_GATEWAY_API_KEY. You can replace the model with any compatible AI SDK provider.

import { gateway, generateText, stepCountIs } from 'ai';
import { search1apiTools } from '@search1api/ai-sdk';

const result = await generateText({
  model: gateway('openai/gpt-5-mini'),
  tools: search1apiTools({ only: ['search', 'crawl'] }),
  stopWhen: stepCountIs(5),
  prompt: 'Find the official AI SDK tool calling docs, read them, and explain how tools work. Cite the URLs you used.',
});

console.log(result.text);

stopWhen lets the model use search results, read a page, and then answer in the same call. The full tool set contains:

ToolModel inputResult
searchquery, optional search_service, page, max_results, include_sites, exclude_sites, time_rangeTitles, links, snippets, and other search response fields
newsSame fields as search except page, with news enginesNews articles and source links
crawl{ url: string }A webpage's title, source URL, and readable content
ask{ query: string }Up to 10 results ranked by relevance, plus the engines and time window used

The model-facing parameters match the MCP server. The model can choose an engine (google, bing, bingcn, duckduckgo, yahoo, yandex, x, reddit, github, youtube, arxiv, wechat, bilibili, imdb, wikipedia, grokipedia; news supports google, bing, duckduckgo, yahoo, and hackernews), return 1–50 results, request a later results page (only bing, bingcn, baidu, and grokipedia paginate), scope or exclude domains, and limit results to the past day, week, month, or year. Result page crawling is not exposed to the model. Unknown arguments are ignored rather than failing the call.

Each tool returns the SDK's typed response. Source URLs and optional metadata are preserved. Empty results stay empty. Ask the model to cite the returned links; the tools do not emit AI SDK source events automatically. When an answer uses grokipedia results, credit them as "Powered by xAI"; see Improving search results.

Agentic search with ask

ask sends a natural-language request to POST /ask. Search1API chooses up to five engines and a time window, drops off-topic results, and returns at most 10 results ranked by relevance. Like the MCP server's ask tool, it is included in search1apiTools() by default. Each call costs 5 credits, compared with 1 credit for search, and has a 45-second timeout.

import { search1apiAsk, search1apiTools } from '@search1api/ai-sdk';

// The previous three-tool set, without ask
const withoutAsk = search1apiTools({ only: ['search', 'news', 'crawl'] });

// ask on its own
const askOnly = { ask: search1apiAsk() };

ask is not available with pay-per-request payments.

Configure individual tools

import { search1apiSearch, search1apiNews, search1apiCrawl } from '@search1api/ai-sdk';

const tools = {
  webSearch: search1apiSearch({
    search: { maxResults: 5, includeSites: ['ai-sdk.dev'], timeRange: 'month' },
  }),
  recentNews: search1apiNews({ news: { maxResults: 3, timeRange: 'day' } }),
  readPage: search1apiCrawl({ crawl: { enableFallback: true } }),
};

Settings passed in code are defaults. When the model supplies the same parameter, its value is used for that call; anything it omits falls back to your settings. Tool sets accept the same settings under search, news, and crawl.

Search and news default to ten results and crawlResults: 0. To include page content in a search response, explicitly set search.crawlResults or news.crawlResults. Each successfully retrieved page is billed separately; see credits and limits.

Client settings and cancellation

Factories and tool sets accept the SDK's apiKey, baseUrl, fetch, headers, timeoutMs, maxRetries, and retryDelayMs settings. You can also inject an existing client:

import { Search1API } from '@search1api/client';

const client = new Search1API({ apiKey: 'your-api-key', timeoutMs: 15_000 });
const tools = search1apiTools({ client });

When client is supplied, other client settings are ignored. Otherwise the tools construct their client on first execution, so module-level tool definitions do not require credentials during a Next.js build.

Pass an abortSignal to generateText or streamText to cancel tool requests. SDK error types, status codes, parsed error bodies, and request IDs are preserved. Retries and timeouts follow the official SDK's configuration.

Next.js route handler

Use the tools on the server and stream UI messages to useChat:

import { search1apiTools } from '@search1api/ai-sdk';
import { convertToModelMessages, gateway, stepCountIs, streamText } from 'ai';
import type { UIMessage } from 'ai';

const tools = search1apiTools({ only: ['search', 'crawl'] });

export async function POST(request: Request) {
  const { messages }: { messages: UIMessage[] } = await request.json();
  const result = streamText({
    model: gateway('openai/gpt-5-mini'),
    system: 'Search and read relevant pages before answering. Cite the URLs you used.',
    messages: await convertToModelMessages(messages),
    tools,
    stopWhen: stepCountIs(5),
    abortSignal: request.signal,
  });
  return result.toUIMessageStreamResponse();
}

The complete Next.js example includes the client chat and renders links from tool outputs.

Source

GitHub · npm · AI SDK tool calling

On this page