> ## Documentation Index > Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Поиск в интернете > POST /api/v1/tools/search — поиск страниц в интернете по текстовому запросу Эндпоинт ищет страницы в интернете по текстовому запросу и возвращает список результатов: заголовок, ссылку, выдержку из страницы и, по запросу, полный текст. Типичное применение — второй этап ответа: модель уточняет факты по свежим источникам, а вы передаёте ей найденные страницы. Модель для вызова не нужна. Запрос уходит на поисковую выдачу, а результаты приходят в том порядке, который задала выдача. ## Минимальный запрос ```bash cURL theme={null} theme={null} curl https://speshu.ai/api/v1/tools/search \ -H "Authorization: Bearer $SPESHU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Как вернуть товар?" }' ``` > [!NOTE] > > Ключ передаётся заголовком `Authorization: Bearer sk-...`. Он создаётся в личном кабинете и показывается один раз — подробности на странице [Аутентификация](https://speshu.ai/docs/authentication.md). ## Поля запроса | Поле | Тип | Описание | | - | - | - | | `query` | string | Поисковый запрос. Обязательно; от 1 до 128 символов. Запрос из одних пробелов не принимается | | `count` | integer | Сколько результатов вернуть. Необязательно; от 1 до 50. По умолчанию 10 | | `ori_question` | string | Исходный вопрос пользователя, которому служит поиск. Необязательно; до 128 символов | | `localization` | string | Подсказка по языку и региону выдачи. Необязательно | | `need_content` | boolean | Возвращать ли текст страницы целиком. Необязательно; по умолчанию `false` | Длины считаются в символах, а не в байтах: кириллический запрос из 100 символов занимает 200 байт и проходит проверку. > [!NOTE] > > Поле `count` необязательное, но значение `0` — ошибка: явный ноль не равен отсутствующему полю. Чтобы получить 10 результатов, не передавайте `count` вовсе. ## Ответ `200 OK`: ```json theme={null} theme={null} { "results": [ { "rerank_score": 0.97, "title": "Возврат товара", "url": "https://example.com/voztrat", "snippet": "Вернуть товар можно в течение 14 дней...", "summary": "Правила возврата товара в течение 14 дней.", "content": "", "site_name": "example.com", "site_icon": "https://example.com/favicon.ico", "date": "2026-06-01", "authority": 80 } ], "usage": { "cost": 0.0004 } } ``` | Поле | Тип | Описание | | - | - | - | | `results` | array | Найденные страницы. Пустой массив — успешный ответ, а не ошибка | | `results[].title` | string | Заголовок страницы | | `results[].url` | string | Адрес страницы | | `results[].snippet` | string | Выдержка из страницы | | `results[].summary` | string | Краткое описание страницы | | `results[].content` | string | Текст страницы. Заполняется, только если в запросе `need_content: true` | | `results[].site_name` | string \| null | Название сайта, если выдача его знает | | `results[].site_icon` | string \| null | Адрес иконки сайта | | `results[].date` | string \| null | Дата публикации в том виде, в каком её отдала выдача | | `results[].authority` | integer | Оценка авторитетности сайта | | `results[].rerank_score` | number | Оценка релевантности результата | | `usage` | object | Расход по вызову. Объект есть всегда, в каждом ответе | | `usage.cost` | number | Сумма, списанная с вашего баланса за вызов. Поле отсутствует, если списание не зафиксировано | > [!NOTE] > > Дата приходит строкой в том виде, в каком её отдала выдача, и может быть `null`. Не разбирайте её как дату ISO без проверки формата. ### Стоимость Стоимость вызова зависит от фактической работы поиска. Поле `usage.cost` — сумма, списанная с вашего баланса; оно отсутствует, если списание не зафиксировано. Поиск, который не нашёл ни одной страницы, не тарифицируется: в этом случае поле `usage.cost` не приходит. Фактический остаток после вызова проверяйте через `GET /api/v1/balance`. ## Проверки перед вызовом | Ситуация | Ответ | | - | - | | Нет ключа или ключ недействителен | `401 invalid_api_key` | | Не хватает денег | `402 insufficient_quota` | | Нет `query`, `query` из одних пробелов, `query` длиннее 128 символов, `count` вне диапазона от 1 до 50, `ori_question` длиннее 128 символов | `400 invalid_request` | | Превышен лимит запросов в минуту | `429 rate_limit_exceeded` | | Превышен лимит потребления в минуту | `429 token_limit_exceeded` | | Поиск недоступен | `503 service_unavailable` | | Поисковая выдача вернула ошибку | `502 upstream_error` | Ошибки приходят в конверте OpenAI — объект `error` с полями `message`, `type`, `param` и `code`. Полная таблица кодов — на странице [Ошибки](https://speshu.ai/docs/errors.md). ## Что дальше > **[Загрузка страницы](https://speshu.ai/docs/api-reference/tools/fetch.md)** > > Текст найденной страницы по ссылке > **[Ранжирование](https://speshu.ai/docs/api-reference/rerank/create.md)** > > Второй этап отбора документов > **[Баланс](https://speshu.ai/docs/api-reference/other/balance.md)** > > Остаток кошелька по валютам > **[Ошибки](https://speshu.ai/docs/errors.md)** > > Полная таблица кодов ## OpenAPI ````yaml api-reference/openapi.json POST /api/v1/tools/search openapi: 3.1.0 info: title: SpeShu.AI API version: 1.0.0 description: >- Единый OpenAI-совместимый API для текстовых моделей, генерации изображений, видео, аудио и музыки. ## Аутентификация Все запросы, кроме `GET /api/v1/models` и `GET /api/v1/media/models`, требуют API-ключ. Ключ передаётся в заголовке `Authorization: Bearer <ключ>` или `X-Api-Key: <ключ>`. ## Ошибки Текстовые эндпоинты (`/chat/completions`, `/responses`, `/messages`) и `/balance` возвращают ошибки в формате OpenAI: ```json { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } ``` Эндпоинты медиа используют собственный конверт: ```json { "code": 422, "msg": "...", "data": null } ``` Подробности — на странице [Ошибки](/errors). servers: - url: https://speshu.ai description: Production security: - BearerAuth: [] tags: - name: Текст description: Генерация текста и диалог - name: Медиа description: Асинхронные задачи генерации изображений, видео, аудио и музыки - name: Хранилище description: Файлы пользователя - name: Справочник description: Каталог моделей и баланс - name: Аудио description: Синтез и распознавание речи - name: Инструменты description: Поиск в интернете и загрузка страниц paths: /api/v1/tools/search: post: tags: - Инструменты summary: Поиск в интернете description: >- Ищет страницы в интернете по текстовому запросу и возвращает заголовок, ссылку, выдержку и, при need_content, текст страницы. Списание зависит от фактической работы поиска; поиск, который не нашёл ни одной страницы, не тарифицируется. operationId: createSearch requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string minLength: 1 maxLength: 128 description: >- Поисковый запрос. Обязательно; от 1 до 128 символов. Запрос из одних пробелов не принимается. count: type: integer minimum: 1 maximum: 50 default: 10 description: >- Сколько результатов вернуть. Необязательно; по умолчанию 10. Значение 0 отклоняется. ori_question: type: string maxLength: 128 description: >- Исходный вопрос пользователя, которому служит поиск. Необязательно. localization: type: string description: Подсказка по языку и региону выдачи. Необязательно. need_content: type: boolean default: false description: Возвращать ли текст страницы целиком. По умолчанию false. responses: '200': description: Найденные страницы. content: application/json: schema: type: object required: - results - usage properties: results: type: array description: >- Найденные страницы. Пустой массив — успешный ответ, а не ошибка. items: type: object properties: rerank_score: type: number description: Оценка релевантности результата. title: type: string description: Заголовок страницы. url: type: string description: Адрес страницы. snippet: type: string description: Выдержка из страницы. summary: type: string description: Краткое описание страницы. content: type: string description: >- Текст страницы. Заполняется, только если в запросе need_content: true. site_name: type: - string - 'null' description: Название сайта, если выдача его знает. site_icon: type: - string - 'null' description: Адрес иконки сайта. date: type: - string - 'null' description: >- Дата публикации в том виде, в каком её отдала выдача. authority: type: integer description: Оценка авторитетности сайта. usage: type: object description: Расход по вызову. Объект есть всегда, в каждом ответе. properties: cost: type: number description: >- Сумма, списанная с вашего баланса за вызов. Отсутствует, если списание не зафиксировано. '400': $ref: '#/components/responses/OpenAIError' '401': $ref: '#/components/responses/OpenAIError' '402': $ref: '#/components/responses/OpenAIError' '429': $ref: '#/components/responses/OpenAIError' '499': $ref: '#/components/responses/OpenAIError' '500': $ref: '#/components/responses/OpenAIError' '502': $ref: '#/components/responses/OpenAIError' '503': $ref: '#/components/responses/OpenAIError' '504': $ref: '#/components/responses/OpenAIError' components: responses: OpenAIError: description: Ошибка в формате OpenAI. content: application/json: schema: $ref: '#/components/schemas/OpenAIError' schemas: OpenAIError: type: object properties: error: type: object properties: message: type: string type: type: string examples: - invalid_request_error description: >- `authentication_error` при 401, `rate_limit_error` при 429, `permission_error` при 403, в остальных случаях `invalid_request_error`, `api_error` или `internal_error`. param: type: - string - 'null' code: type: - string - 'null' examples: - invalid_request description: >- Машиночитаемый код: `invalid_api_key`, `unauthorized`, `insufficient_quota`, `rate_limit_exceeded`, `token_limit_exceeded`, `content_too_large`, `limit_exceeded`, `model_not_found`, `no_providers`, `service_unavailable`, `provider_error`, `invalid_request`, `context_length_exceeded`, `internal_error`. required: - message - type required: - error securitySchemes: BearerAuth: type: http scheme: bearer description: >- API-ключ в формате `sk-...`. Альтернативно — заголовок `X-Api-Key: sk-...` (совместимо с Anthropic SDK). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.