BOX 3.2
BOX 3.2: поля API и правила заполнения
BOX 3.2: поля API и правила заполнения: подробная инструкция, назначение полей, порядок действий и иллюстрации интерфейса.
На этой странице
Типы, обязательность и идентификаторы
requiredозначает, что ключ должен присутствовать в запросе. Это не всегда запрет пустой строки: нужен отдельныйminLengthили серверная проверка.null, отсутствующий ключ, пустой массив и пустая строка могут обрабатываться по-разному. Не используйте их как взаимозаменяемые значения.id,uuid, имя и человекочитаемый заголовок — разные поля. Берите ID из ответа каталога, а не из порядкового номера строки.- Проценты, доли 0–1, пиксели и нормализованные координаты не смешиваются. Значение
80в UI «Порог, %» нельзя автоматически перенести в поле API, ожидающее 0.8. - Целое поле времени не раскрывает его единицу. Если схема/описание не уточняет секунды, миллисекунды или локальное время суток, проверьте описание параметров операции.
- При постраничной выдаче обрабатывайте все страницы и сверяйте общее число записей. Проверяйте пустую выборку отдельно от отказа доступа и ошибки сервера.
На экране: Обязательные поля и типы данных на примере CreateCamera.
Камера — CreateCamera
| Ключ | Тип / значение | Соответствие |
|---|---|---|
name |
string, обязателен | Название |
media_uri |
string, обязателен | Адрес/идентификатор источника; формат зависит от типа |
camera_type |
CameraType |
Тип подключения |
is_enabled |
boolean, default true | Камера включена |
is_record |
boolean или null | Видеозапись |
is_disable_inference |
boolean или null, default false | Обратный флаг: true отключает аналитику |
is_to_gray_image |
boolean | Монохромное преобразование |
object_id |
integer или null | Родительский объект |
categories_presets |
массив CategoriesPreset или null |
Назначенные пресеты |
etc_params |
string или null | JSON дополнительных параметров передаётся строкой по этой схеме |
obj_map_coords |
string или null | Сериализованное размещение на плане |
location_info |
объект LocationInfo |
Координаты/высота/уровень и связанные параметры |
number |
string или null | Дополнительный номер источника |
params |
DetectorParams или null |
Специальные параметры детектора, в том числе теплового |
Перечисление CameraType в схеме шире пользовательского списка: RTSP_UDP=0, RTSP_TCP=1, SNAPSHOT=2, XMEYE=3, JETSON=4, MOBOTIX_TR=5, MULTIFILE=6, V4L2=7, DASHCAM=8, VIRTUAL=9, MEDIAMTX=10, MILESTONE=11, GENERIC_CAMERA=12, HLS=13. UI может объединять технические варианты под одним названием, например «Стационарная камера».
Зона и пресет
| Схема / ключ | Значение |
|---|---|
CreateZone.zid |
Системный тип зоны, обязателен; это не пользовательское название |
CreateZone.is_active |
Обязательный флаг активности в модели API |
CreateZone.polygon |
Обязательная вложенная геометрия: массивы целочисленных координат. Порядок осей и систему координат берите из описания редактора или операции |
CreateZone.color_hex |
Обязательный HEX-цвет |
CreateZone.title |
Человекочитаемое название |
CreateZone.is_enabled |
Отдельный флаг, default true; не подменяйте им is_active без понимания операции |
CategoriesPreset.name, description |
Название и описание набора |
violation_categories, event_categories, detection_categories |
Массивы категорий, разделённые по назначению |
cameras_ids |
Массив ID использующих камер |
is_enabled |
Состояние пресета в схеме API |
Матрица — MatrixRuleRequest
Обязательны priority и event_threshold. camera_ids — массив, а camera_id — отдельное исторически присутствующее поле; используйте схему запроса актуальной операции, не передавайте противоречащие значения в оба. primary_category/secondary_category и множественные варианты в этой модели представлены строками; не превращайте множественную строку в произвольный массив без проверки схемы.
time_from/time_to имеют служебное значение по умолчанию −1; это не время «минус одна секунда» в пользовательском расписании. cron_datetime содержит календарное условие, person_violator_ids — список персон, recognized — параметр распознавания, status — отдельная структура состояния.
DecisionMatrixSolution: 0 — REJECT, 1 — COMMIT_VIOLATION, 2 — SET_TYPE_EVENT, 3 — SET_TYPE_VIOLATION. Название кода COMMIT_VIOLATION не следует самостоятельно трактовать как обязательную переклассификацию в нарушение: пользовательское действие «Зафиксировать» по функциональному описанию сохраняет исходный тип.
Персоны, пользователи и наряды
| Схема | Ключевые поля и отличия |
|---|---|
CreatePerson |
Обязательные ключи personnel_number, firstname, surname, patronymic. У patronymic нет ограничения минимальной длины в схеме, а текущая UI-форма не требует отчество. position в API nullable, хотя UI требует должность. subdivision_id, images, is_works задают подразделение, изображения и состояние |
CreateUser |
Обязателен только username на уровне этой модели; UI требует больше реквизитов. roles_v2/roles_v2_configs относятся к ролевой модели, ui_lang/ui_theme_type — к интерфейсу, telegram_username/vkteams_username — к каналам. Не путайте пользователя с персоной |
CreateJobDocument |
Обязательны document_type, document_number, is_active. Плановые job_time_from/to отделены от фактических actual_time_from/to; workers — ID работников; camera_storage_zone_ids — ID зон; persons_count — количество людей |
График присутствия — ZonesScheduleList и ZonesSchedule
Внешняя структура содержит time_zone и массив schedules. В каждой строке обязательны zone_ids, priority, days_of_week, границы рабочего времени и перерыва, минимальное/максимальное количество людей для рабочего времени, перерыва и нерабочего периода.
Поля work_time_seconds_from/to и break_time_seconds_from/to явно используют секунды времени суток по правилам задания расписания, а не текст 08:00. Для 08:00 это 28800; часовой пояс берётся из внешней структуры. ObjectVisitResetSchedule.day_seconds аналогично задаёт время суточного сброса. Не используйте такое число как абсолютную дату Unix без проверки операции.
LLM, промпт и расписание камеры
| Схема / ключ | Значение |
|---|---|
LLMInput.name |
Обязательное имя подключения |
llm_driver, llm_model, llm_version |
Драйвер и идентификатор модели |
work_instances |
Массив соединений WorkInstance |
WorkInstance.agent_url, token, url_proxy |
Адрес, секрет доступа и прокси |
basicauth_user, basicauth_password, max_connections |
Дополнительная аутентификация и лимит соединений |
PromptInput.name, prompt_text, llm_id |
Обязательные имя, инструкция и ID модели |
prompt_type |
Тип обработки промпта. Значение scenario_execution присутствует в схеме API, но не является доступным типом в описанной форме BOX 3.2. Перед его использованием нужен совместимый маршрут исполнения; для обычной настройки выбирайте тип из интерфейса. |
json_schema |
Строка с JSON-схемой или null, а не непосредственно JSON-объект в этой модели |
normalize_coords |
Флаг нормализации координат: boolean или null, значение по умолчанию false. Шкалу и систему координат должен поддерживать обработчик выбранного режима. Не меняйте флаг без проверки рамок на тестовом изображении. |
draw_event_rect, rect_color_hex, rect_thickness, rect_expand |
Нанесение и параметры рамки исходного события |
metadata |
Дополнительные данные в строковом представлении JSON |
CameraPromptSchedule.camera_id |
Обязательный ID камеры |
type, interval_value, week_day, time |
Настройки выбранной периодичности |
event_category |
Категория событийного запуска |
cron_interval, cron_intervals, second_interval |
Дополнительные/совместимые варианты расписания API; заполняйте только поля, предусмотренные схемой выбранной операции |
time_range_start, time_range_end |
Границы суточного диапазона; UI показывает UTC |
is_crop, crop_cords |
Использование фрагмента кадра и его координаты |
frame_buffer_size |
Размер буфера кадров: целое число или null. Допустимый диапазон, порядок кадров и способ передачи модели зависят от обработчика. Получите эти правила для своей версии перед настройкой автоматического сравнения. |
EventConfirmationStatus содержит 0=ALL, 1=NO_STATUS, 2=CONFIRMED, 3=DENIED, 4=WITHOUT_REVIEW. ALL — не содержательное решение модели. В документированном примере верификации используются 1/2/3; не расширяйте ответ всеми значениями перечисления только потому, что они есть в API.
Для интегратора полезны операции получения промпта, истории изменений, конкретной версии, запуска и результата выполнения в группе /api/inference/llm_integration/. Их существование подтверждает техническую возможность работы с данными, но не заменяет проверку прав и поведения операции.
