> For the complete documentation index, see [llms.txt](https://visaver.gitbook.io/visaver-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://visaver.gitbook.io/visaver-api/dokumentaciya/poisk-po-soderzhimomu.md).

# Поиск по содержимому

## Поиск по содержимому

**POST** `/search/`

Выполняет поиск по содержимому обработанных видео.

### Тело запроса

Поиск по одной задаче:

```json
{
    "query": "поисковая фраза",
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "n_results": 5
}
```

Поиск по нескольким задачам:

```json
{
    "query": "поисковая фраза",
    "job_ids": [
        "123e4567-e89b-12d3-a456-426614174000",
        "456e7890-e12b-34c5-d678-901234567890"
    ],
    "n_results": 10
}
```

### Параметры

| Параметр    | Описание                                                          |
| ----------- | ----------------------------------------------------------------- |
| `query`     | Поисковый запрос                                                  |
| `job_id`    | UUID одной задачи (взаимоисключающе с `job_ids`)                  |
| `job_ids`   | Массив UUID задач (взаимоисключающе с `job_id`)                   |
| `n_results` | Максимальное количество результатов, от 1 до 50 (по умолчанию: 5) |

### Пример запроса

```bash
curl -X POST "https://your-domain.com/search/" \
  -H "vendor-key: your-vendor-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "машинное обучение",
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "n_results": 5
  }'
```

### Ответ

```json
{
    "result": "ok",
    "data": [
        {
            "job_id": "123e4567-e89b-12d3-a456-426614174000",
            "start_from": 45.5,
            "end_to": 67.2,
            "text": "В этом разделе мы рассмотрим основы машинного обучения",
            "similarity": 0.87,
            "image": "https://your-domain.com/frames/frame/vendor-key/job-id/45"
        }
    ],
    "query": "машинное обучение",
    "total_results": 3
}
```

### Описание полей ответа

| Поле                | Описание                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| `result`            | Статус выполнения поиска (`ok` или `error`)                             |
| `data`              | Массив результатов поиска                                               |
| `data[].job_id`     | UUID задачи, в которой найден фрагмент                                  |
| `data[].start_from` | Время начала найденного фрагмента (в секундах)                          |
| `data[].end_to`     | Время окончания найденного фрагмента (в секундах)                       |
| `data[].text`       | Найденный текстовый фрагмент                                            |
| `data[].similarity` | Коэффициент релевантности (от 0 до 1)                                   |
| `data[].image`      | URL изображения кадра для данной временной метки (если доступны frames) |
| `query`             | Оригинальный поисковый запрос                                           |
| `total_results`     | Общее количество найденных результатов                                  |

### Особенности поиска

* **Обогащение результатов** — если для задачи доступны кадры (frames), результаты автоматически дополняются ссылками на изображения.
* **Ранжирование** — результаты сортируются по релевантности (similarity).
* **Контекст** — каждый результат включает временные рамки для точного позиционирования в видео.

### Ошибки поиска

При ошибке поиска API возвращает:

```json
{
    "detail": "Search request failed: описание ошибки"
}
```

Возможные причины ошибок:

* Задачи еще не обработаны полностью.
* Отсутствуют права доступа к указанным задачам.
* Проблемы с подключением к поисковому сервису.
* Некорректные параметры запроса.

## Семантический поиск

**POST** `/semantic_search/`

Семантический (векторный) поиск по содержимому. Формат запроса и ответа полностью совпадает с **POST** `/search/`: `query`, `job_id` или `job_ids`, `n_results`.

Отличия:

* Для задачи должен быть заказан продукт `semantic_search`: указан в `actions` при создании задачи или дозаказан через reorder.
* Поиск выполняется по векторному индексу с реранжированием — находит совпадения по смыслу, а не только по вхождению слов.

## Мультимодальный поиск

**POST** `/multimodal_search/`

Поиск по кадрам видео.

Запрос включает `job_id` или `job_ids`, `n_results` и хотя бы одно из полей:

* `query` — текст;
* `image_base64` — картинка в формате Data URL, например `data:image/jpeg;base64,...`.

Отличия:

* Для задачи должен быть заказан продукт `multimodal_search`.
* Результаты содержат `job_id`, `frame_url` — кадр видео, хостится поисковым сервисом, `score` и `timestamp` — секунду видео, где найдено совпадение.