diff --git a/docs/proxy/config_settings.md b/docs/proxy/config_settings.md index 2cb026249..b3c1c90ee 100644 --- a/docs/proxy/config_settings.md +++ b/docs/proxy/config_settings.md @@ -795,6 +795,9 @@ router_settings: | SAMBANOVA_API_BASE | Base URL for SambaNova. Default is https://api.sambanova.ai/v1 | SCX_API_BASE | Base URL for SCX.ai. Default is https://api.scx.ai/v1 | SCX_API_KEY | API key for SCX.ai +| SEARCH1API_API_BASE | Base URL for the Search1API search provider. Default is https://api.search1api.com +| SEARCH1API_API_KEY | API key for the Search1API search provider +| SEARCH1API_KEY | Fallback API key for the Search1API search provider, the name Search1API's own CLI and SDKs read | SEARCHAPI_API_BASE | Base URL for the SearchApi search provider | SERPER_API_BASE | Base URL for the Serper search provider | SONIOX_API_BASE | Base URL for Soniox. Default is https://api.soniox.com diff --git a/docs/search/index.md b/docs/search/index.md index 134708b7b..4f14bec47 100644 --- a/docs/search/index.md +++ b/docs/search/index.md @@ -2,7 +2,7 @@ | Feature | Supported | |---------|-----------| -| Supported Providers | `perplexity`, `tavily`, `parallel_ai`, `exa_ai`, `brave`, `google_pse`, `dataforseo`, `firecrawl`, `searxng`, `linkup`, `duckduckgo`, `searchapi`, `serper`, `you_com`, `apiserpent`, `agentcore`, `nimble`, `bing_grounding` | +| Supported Providers | `perplexity`, `tavily`, `parallel_ai`, `exa_ai`, `brave`, `google_pse`, `dataforseo`, `firecrawl`, `searxng`, `linkup`, `duckduckgo`, `searchapi`, `serper`, `you_com`, `apiserpent`, `agentcore`, `nimble`, `bing_grounding`, `search1api` | | Cost Tracking | ✅ | | Logging | ✅ | | Load Balancing | ❌ | @@ -217,7 +217,7 @@ See the [official Perplexity Search documentation](https://docs.perplexity.ai/ap | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string or array | Yes | Search query. Can be a single string or array of strings | -| `search_provider` | string | Yes (SDK) | The search provider to use: `"perplexity"`, `"tavily"`, `"parallel_ai"`, `"exa_ai"`, `"brave"`, `"google_pse"`, `"dataforseo"`, `"firecrawl"`, `"searxng"`, `"linkup"`, `"duckduckgo"`, `"searchapi"`, `"serper"`, or `"you_com"` or `"apiserpent"` or `"agentcore"` or `"bing_grounding"` | +| `search_provider` | string | Yes (SDK) | The search provider to use: `"perplexity"`, `"tavily"`, `"parallel_ai"`, `"exa_ai"`, `"brave"`, `"google_pse"`, `"dataforseo"`, `"firecrawl"`, `"searxng"`, `"linkup"`, `"duckduckgo"`, `"searchapi"`, `"serper"`, or `"you_com"` or `"apiserpent"` or `"agentcore"` or `"bing_grounding"` or `"search1api"` | | `search_tool_name` | string | Yes (Proxy) | Name of the search tool configured in `config.yaml` | | `max_results` | integer | No | Maximum number of results to return (1-20). Default: 10 | | `search_domain_filter` | array | No | List of domains to filter results (max 20 domains) | @@ -291,6 +291,7 @@ The response follows Perplexity's search format with the following structure: | Bedrock AgentCore | `AGENTCORE_GATEWAY_URL` (required), AWS credentials or `AGENTCORE_GATEWAY_TOKEN` | `agentcore` | | Nimble | `NIMBLE_API_KEY` | `nimble` | | Grounding with Bing (Microsoft Foundry) | `BING_GROUNDING_PROJECT_ENDPOINT`, `BING_GROUNDING_MODEL` (required), `api_key` or `BING_GROUNDING_TOKEN` or azure-identity | `bing_grounding` | +| Search1API | `SEARCH1API_API_KEY` | `search1api` | See the individual provider documentation for detailed setup instructions and provider-specific parameters. diff --git a/docs/search/search1api.md b/docs/search/search1api.md new file mode 100644 index 000000000..2e49d1ce3 --- /dev/null +++ b/docs/search/search1api.md @@ -0,0 +1,112 @@ +# Search1API Search + +**Get API Key:** [https://app.s1.dev/api-keys](https://app.s1.dev/api-keys) + +[Search1API](https://s1.dev) is a web search API for AI agents that fronts Google, Bing, DuckDuckGo, Yahoo and site-specific engines (GitHub, arXiv, Reddit, YouTube, Wikipedia and more) behind one endpoint. One search costs 1 credit. + +## LiteLLM Python SDK + +```python showLineNumbers title="Search1API Search" +import os +from litellm import search + +os.environ["SEARCH1API_API_KEY"] = "..." + +response = search( + query="latest AI developments", + search_provider="search1api", + max_results=5 +) + +for result in response.results: + print(f"{result.title}: {result.url}") + print(f"Snippet: {result.snippet}\n") +``` + +## LiteLLM AI Gateway + +### 1. Setup config.yaml + +```yaml showLineNumbers title="config.yaml" +model_list: + - model_name: gpt-5.6 + litellm_params: + model: gpt-5.6 + api_key: os.environ/OPENAI_API_KEY + +search_tools: + - search_tool_name: search1api-search + litellm_params: + search_provider: search1api + api_key: os.environ/SEARCH1API_API_KEY +``` + +### 2. Start the proxy + +```bash +litellm --config /path/to/config.yaml + +# RUNNING on http://0.0.0.0:4000 +``` + +### 3. Test the search endpoint + +```bash showLineNumbers title="Test Request" +curl http://0.0.0.0:4000/v1/search/search1api-search \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "latest AI developments", + "max_results": 5 + }' +``` + +## Unified Parameters + +| Unified spec parameter | Mapped to Search1API parameter | +|------------------------|-------------------------------| +| `max_results` | `max_results` (1-50; the unified default of 10 is sent when omitted) | +| `search_domain_filter` | `include_sites`; entries prefixed with `-` go to `exclude_sites` | +| `country` | *ignored (no equivalent; use `language` below)* | +| `max_tokens_per_page` | *ignored (no equivalent)* | + +## Provider-specific Parameters + +```python showLineNumbers title="Search1API Search with Provider-specific Parameters" +import os +from litellm import search + +os.environ["SEARCH1API_API_KEY"] = "..." + +response = search( + query="vector database benchmarks", + search_provider="search1api", + max_results=5, + # Search1API-specific parameters + search_service="github", # google (default), bing, duckduckgo, yahoo, x, reddit, + # github, youtube, arxiv, wechat, bilibili, imdb, wikipedia + time_range="month", # day, week, month, year + language="en", # language code, e.g. en, zh, de +) + +for result in response.results: + print(result.title, result.url) +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| `search_service` | string | Engine to query. Defaults to `google` | +| `time_range` | string | `day`, `week`, `month` or `year` | +| `language` | string | Language code for the results, e.g. `en`, `zh`, `de` | +| `include_sites` | array | Only return results from these sites. Wins over `search_domain_filter` when both are given | +| `exclude_sites` | array | Drop results from these sites. Wins over `search_domain_filter` when both are given | + +Search1API's `crawl_results` and `image` parameters are rejected with a `ValueError`: the unified response has no field for fetched page text or image URLs, and each fetched page would bill an extra credit that LiteLLM cost tracking cannot see. Call Search1API's `/crawl` endpoint directly when you need page content. + +See the [Search1API search reference](https://s1.dev/docs/basic/search) for the full parameter set. + +## Response Notes + +Search1API returns `title`, `link` and `snippet` for each result, which map onto the unified `title`, `url` and `snippet` fields. There is no publication date, so `date` is always `null`. + +Set `SEARCH1API_API_BASE` to override the default `https://api.search1api.com` endpoint. `SEARCH1API_KEY`, the variable Search1API's own CLI and SDKs read, is honored as a fallback when `SEARCH1API_API_KEY` is not set. diff --git a/sidebars.js b/sidebars.js index 4bbeb3866..ec9a2f4a4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -977,6 +977,7 @@ const sidebars = { "search/agentcore", "search/nimble", "search/bing_grounding", + "search/search1api", ] }, "skills",