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

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

**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` - Максимальное количество результатов (по умолчанию: 5)

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

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

### Ответ

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

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

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

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

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

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

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

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

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://visaver.gitbook.io/visaver-api/dokumentaciya/poisk-po-soderzhimomu.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.