# Веб-поиск в реальном времени для AI.

**API:** Data API

**Endpoint:** `POST /v1/beta/byteplus/web-search`

**Tags:** BytePlus

Выполняет веб-поиск в реальном времени, созданный для AI-агентов, и возвращает ранжированный список результатов с заголовками, ссылками и фрагментами. `Query` обязателен; сузьте набор результатов с помощью `Count` (≤ 20), `Filter` (ограничить `Sites` или исключить `BlockHosts`), `Language` и `TimeRange`. Ответ оборачивает `ResponseMetadata.RequestId` и список `Result` с веб-результатами. Используйте для дополнения RAG-выборки, мониторинга конкурентов/PR, проверки фактов и поиска источников контента; каждый URL результата передавайте в `post_byteplus_fetch`, чтобы получить полный контент страницы.

### Справочные данные о ценах

- Тарификация: фиксированная базовая стоимость успешного запроса.
- Ориентировочная стоимость запроса: USD 0.0048.
- Справочный множитель для клиента: 1.0. Не применяйте его повторно к уже рассчитанной сумме клиента.

Справочные метаданные, а не коммерческое предложение для аккаунта, гарантированная цена или лимит расходов. Кредиты ресурсов — не кредиты Felo. Итоговые списания определяются записями биллинга Felo.

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Request body

Required: **yes**

### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "Query": {
      "type": "string",
      "description": "Поисковый запрос. Обязательно. Максимум 400 символов; движок upstream также фактически ограничивает примерно 50 словами.",
      "example": "OpenAI news",
      "maxLength": 400
    },
    "Count": {
      "type": "integer",
      "description": "Количество возвращаемых результатов. Необязательно; по умолчанию 10, максимум 20.",
      "maximum": 20,
      "example": 10,
      "default": 10
    },
    "Filter": {
      "type": "object",
      "description": "Необязательный фильтр результатов. Оба поля — строки полных доменов через вертикальную черту (не более 5 в каждом).",
      "properties": {
        "Sites": {
          "type": "string",
          "description": "Ограничить результаты этими полными доменами. Через вертикальную черту, максимум 5, например \"bytedance.com|byteplus.com\". (Передача массива возвращает 10400 Invalid Parameter.)",
          "example": "bytedance.com|byteplus.com"
        },
        "BlockHosts": {
          "type": "string",
          "description": "Исключить результаты с этих полных доменов. Через вертикальную черту, максимум 5, например \"reddit.com|quora.com\".",
          "example": "reddit.com|quora.com"
        }
      }
    },
    "Language": {
      "type": "string",
      "description": "Необязательная подсказка языка в формате upstream, например EN, ZH-HANS, ZH-HANT.",
      "example": "EN"
    },
    "TimeRange": {
      "description": "Необязательное окно свежести. Одно из именованных окон OneDay / OneWeek / OneMonth / OneYear или пользовательский диапазон \"YYYY-MM-DD..YYYY-MM-DD\". Не указывайте, чтобы не фильтровать по времени. ПРИМЕЧАНИЕ: значения вроде \"week\"/\"month\" upstream молча игнорирует.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "OneDay",
            "OneWeek",
            "OneMonth",
            "OneYear"
          ]
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2}$",
          "description": "Пользовательский диапазон, например 2026-08-01..2026-09-01."
        }
      ],
      "example": "OneWeek"
    }
  },
  "required": [
    "Query"
  ]
}
```

Example:

```json
{
  "Query": "OpenAI news"
}
```

## Responses

### 200 — Поиск успешно завершён. `Result` содержит ранжированные веб-результаты.

Headers:
- `X-Request-Id` (string) — Идентификатор запроса, который нужно указать при обращении в поддержку Felo.

**application/json**

Schema: object

```json
{
  "type": "object",
  "properties": {
    "ResponseMetadata": {
      "type": "object",
      "description": "Метаданные запроса upstream.",
      "properties": {
        "RequestId": {
          "type": "string",
          "description": "Уникальный идентификатор этого запроса."
        },
        "Action": {
          "type": "string"
        },
        "Version": {
          "type": "string"
        },
        "Service": {
          "type": "string"
        },
        "Region": {
          "type": "string"
        }
      }
    },
    "Result": {
      "type": "object",
      "description": "Полезная нагрузка результатов поиска.",
      "properties": {
        "ResultCount": {
          "type": "integer",
          "description": "Количество возвращённых веб-результатов."
        },
        "WebResults": {
          "type": "array",
          "description": "Ранжированный список веб-результатов.",
          "items": {
            "type": "object",
            "properties": {
              "Id": {
                "type": "string",
                "description": "Непрозрачный id результата."
              },
              "SortId": {
                "type": "integer",
                "description": "Ранг результата, начиная с 1."
              },
              "Title": {
                "type": "string",
                "description": "Заголовок результата."
              },
              "SiteName": {
                "type": "string",
                "description": "Название сайта-источника (может быть пустым)."
              },
              "Url": {
                "type": "string",
                "description": "URL результата."
              },
              "Snippet": {
                "type": "string",
                "description": "Короткий фрагмент текста со страницы."
              },
              "Summary": {
                "type": "string",
                "description": "Более длинная сводка содержимого страницы."
              },
              "PublishTime": {
                "type": "string",
                "description": "Время публикации в ISO 8601 (может быть пустым)."
              },
              "PublishTimeUnix": {
                "type": "integer",
                "description": "Время публикации в секундах Unix (0, если неизвестно)."
              },
              "LogoUrl": {
                "type": "string",
                "description": "Подписанный URL логотипа сайта (ограничен по времени)."
              }
            }
          }
        },
        "SearchContext": {
          "type": "object",
          "description": "Копия разрешённого контекста запроса.",
          "properties": {
            "OriginQuery": {
              "type": "string"
            },
            "SearchType": {
              "type": "string"
            }
          }
        },
        "TimeCost": {
          "type": "integer",
          "description": "Время обработки upstream в миллисекундах."
        },
        "LogId": {
          "type": "string",
          "description": "ID журнала upstream (равен ResponseMetadata.RequestId)."
        },
        "Choices": {
          "type": [
            "array",
            "null"
          ],
          "description": "Зарезервировано; null, если неприменимо.",
          "items": {
            "type": "object"
          }
        },
        "Usage": {
          "type": [
            "object",
            "null"
          ],
          "description": "Зарезервировано; null, если неприменимо."
        }
      }
    }
  }
}
```

Example:

```json
{
  "ResponseMetadata": {
    "RequestId": "20260904155503A787EC832774768DC56F",
    "Action": "",
    "Version": "",
    "Service": "",
    "Region": ""
  },
  "Result": {
    "ResultCount": 3,
    "WebResults": [
      {
        "Id": "19b903d59c017bbb04c7832574500d49",
        "SortId": 1,
        "Title": "OpenAI News | OpenAI",
        "SiteName": "OpenAI",
        "Url": "https://openai.com/news/",
        "Snippet": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.",
        "Summary": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.",
        "PublishTime": "2026-09-03T07:50:20+08:00",
        "PublishTimeUnix": 1788393020,
        "LogoUrl": "https://p16-bpsearch-sign.ibyteimg.com/...<signed>"
      }
    ],
    "SearchContext": {
      "OriginQuery": "OpenAI latest news",
      "SearchType": "web"
    },
    "TimeCost": 935,
    "LogId": "20260904155503A787EC832774768DC56F",
    "Choices": null,
    "Usage": null
  }
}
```

### 400 — Запрос не удалось обработать. Проверьте параметры запроса.

### 401 — Требуется действительный API-ключ Felo.

### 402 — Запрос не может быть выполнен: не выполнено требование биллинга.

### 403 — Аккаунту не разрешено выполнять эту операцию.

### 429 — Достигнут лимит запросов или расходов.

### 502 — Сервис не смог выполнить запрос.

### 503 — API или сервис биллинга временно недоступны.

### 504 — Истекло время ожидания обработки запроса.

### default — Ответ с ошибкой; сквозные ответы upstream могут использовать форматы провайдера

**application/json**

Schema:

```json
{}
```