# FaceStream version 5.2.6

### Introduction

All URLs must be prefixed with API version like so: `http://127.0.0.1:34569/api/1`. This document describes FaceStream backend service API. The service is capable of:

- getting current streams,
- providing streams preview.

Refer to `streams` API for details on how to get stream params.

Refer to `streams/preview` API for details on how to get stream preview.

Refer to `metrics` API for details on how to get streams metrics.

### API Versioning

Actual FaceStream version is available by URL like this: `http://127.0.0.1:34569/version`.

### Notes

The type returned from `streams` and `streams/{id}` depends on `lunastreams.api_version` from FACE_STREAM_CONFIG

### /streams

Stream API allows clients to get information about processing streams.

It is also possible to request a video preview for the particular stream. Refer to `streams/preview/` API for details.

#### /streams get

get

Get list of current stream parameters. The response body will contain an array of JSON objects.

#### get /streams

Get list of current stream parameters. The response body will contain an array of JSON objects.

## HTTP status code 200

### Body

Media type: application/json

Possible types:

- stream_info_v2

  - account_id: required(string)

    new stream account ID for authentication in Luna Platform

  - stream_id: required(string)

    stream UUID

  - name: required(string)

    display name

  - description: (string)

    new stream description

  - preview_url: required(string)

    stream preview URL

  - status: required(string)

    stream status

  - version: required(integer)

    stream version

  - error: required(string)

    stream error

  - data: required(object)

    stream input parameters

    - analytics: required(array of analytics)

      Items: analytics

      - enabled: (boolean)

        determines if analytics is enabled

      - mode: (one of 1, 2, 3, 4)

        analytics mode 1 - "faces", 2 - "bodies", 3 - "humans", 4 - "fighting", by default 3 - "humans"

      - droi: (object)

        region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

        - x: required(number)

          x coordinate

        - y: required(number)

          y coordinate

        - width: required(number)

          width

        - height: required(number)

          height

        - mode: required(one of abs, percent)

          coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

      - event_handler: required(object)

        parameters related to sending the best shots to Luna Platform and processing them using handlers

        - type: (string)

          handler type, by default "luna_handler"

        - handler_id: required(string)

          handler id in Luna Platform

        - frame_store: (string)

          frame store URL

        - authorization: required(object)

          authorization for requests to the Luna API service of the Luna Platform

          - token: required(string)
      - filtering: (object)

        stream filtering parameters

        - min_score_face: (number)

          score that defines face detection quality, threshold for filtering detections sent to the server, by default 0.5187.

        - min_score_body: (number)

          score that defines body detection quality, threshold for filtering detections sent to the server, by default 0.5.

        - min_body_size_threshold: (number)

          body detection size, less than which it will not be sent for processing, by default 0 (filtering by size is disabled).

        - detection_yaw_threshold: (integer)

          sets the maximum value of head yaw angle in relation to camera, by default 40.

        - detection_pitch_threshold: (integer)

          sets the maximum value of head pitch angle in relation to camera, by default 40.

        - detection_roll_threshold: (integer)

          sets the maximum value of head roll angle in relation to camera, by default 30.

        - yaw_number: (integer)

          defines the number of frames for image filtration based on head tilt angle, by default 1.

        - yaw_collection_mode: (boolean)

          sets the number of frames the system must collect to analyze head yaw angle, by default false.

        - mouth_occlusion_threshold: (number)

          determines how much the mouth can be obscured in the frame, by default 0.0.

      - liveness: (object)

        stream liveness parameters

        - use_mask_liveness_filtration: (boolean)

          enables checking the presence of a real person in the frame based on backgrounds, by default false.

        - use_flying_faces_liveness_filtration: (boolean)

          enables checking the presence of a real person in the frame based on the facial surrounding, by default false.

        - liveness_mode: (integer)

          enables to specify which frames from a track will undergo Liveness check. There are three options for selecting a frame

        - number_of_liveness_checks: (integer)

          enables to specify the number of frames to check for Liveness. The specified value is used in the liveness-mode parameter. By default 10.

        - liveness_threshold: (number)

          is used to define the presence of a real person in a frame. The system confirms that it is a real person in the frame, and not a photo, only if Liveness returned a value higher than the one specified in the parameter. By default 0.8.

        - livenesses_weights: (array of any)

          determines the involvement of each liveness check type (mask, and flying_faces) in the resulting estimation of the presence of a human face in the frame. By default [0.25, 0.75].

        - mask_backgrounds_count: (integer)

          the number of background frames that are used for the corresponding checks, by default 300.

      - primary_track_policy: (object)

        stream primary track policy parameters

        - use_primary_track_policy: (boolean)

          is used in cases of Access Control Systems (turnstiles/gates at the office/bank entrances) for easier control and face recognition implementation in a secured area, by default false.

        - best_shot_min_size: (integer)

          sets a minimal size for detections within Primary Track policy, by default 70.

        - best_shot_proper_size: (integer)

          sets the size of detection for Primary Track policy. When a detection reaches the defined value, track immediately sends all its best shots to the server, by default 140.

      - sending: (object)

        stream sending parameters

        - time_period_of_searching: (integer)

          interval in track after the end of which a best shot is sent to the server, by default -1.

        - silent_period: (integer)

          interval between period. Once the analysis period is over, the system holds this silent_period before starting next period of frame analysis, by default -1.

        - type: (string)

          sets the measurement metric for analysis periods and intervals between those (per frames or per seconds), by default "sec".

        - bestshot_settings: (object)

          settings of which bestshots will be sent to platform

          - face_bestshots_to_send: (integer)

            number of face frames that the user sets to receive from the track or certain periods of this track, by default 1.

          - body_bestshots_to_send: (integer)

            number of body frames that the user sets to receive from the track or certain periods of this track, by default 1.

          - type: (one of 1, 2, 3, 4)

            bestshot mode 1 - "faces_only", 2- "bodies_only", 3 - "faces_with_bodies", 4 - "separately", by default 3 - "faces_with_bodies"

        - body: (object)

          body periodic sending settings

          - send_only_full_set: (boolean)

            send data only if the required number of best shots and detections have been collected, by default true.

          - delete_track_after_sending: (boolean)

            whether to delete the best shots and detections after sending the data, by default false.

        - full_frame_settings: (one of 1, 2, 3, 4)

          defines which source frames will be sent to Luna Platform 1 - "faces_only", 2- "bodies_only", 3 - "faces_with_bodies", 4 - "separately", by default 3 - "faces_with_bodies"

      - healthcheck: (object)

        stream health check parameters

        - max_error_count: (integer)

          error count limit in period to consider stream to be alive, by default 10

        - period: (integer)

          see description of max_error_count, measured in seconds, by default 3600

        - retry_delay: (integer)

          time gap (in seconds) between attempts to reopen not alive stream, by default 5

        - timeout: (integer)

          timeout in milliseconds that is set to read the encoded packet

    - ffmpeg_threads_number: (integer)

      number of threads for video decoding, by default 0 - chosen by decoder library

    - frame_processing_mode: (one of auto, full, scale)

      determines whether full or scaled frame will be processed, by default "auto" - depends on FACE_STREAM_CONFIG param 'convertFullFrame'

    - real_time_mode_fps: required(integer)

      the video is processed with the specified number of FPS. The video can’t be processed with FPS higher than the one specified in this parameter

    - reference: required(string)

      camera address, e.g.

    - type: required(one of tcp, udp, videofile, images)

      transport protocol for rtsp camera, by default "tcp"

    - roi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - rotation: (integer)

      angle of camera frame rotation, possible values are 0, 90, 180, 270, by default 0

    - preferred_program_stream_frame_width: (integer)

      frame width of the preferred program stream, by default 800

    - endless: (boolean)

      determines if stream is endless

  - location: (object)

    stream source location parameters

    - city: (string - maxLength: 36)

      city where event is incidented

    - area: (string - maxLength: 36)

      area where event is incidented

    - district: (string - maxLength: 36)

      district where event is incidented

    - street: (string - maxLength: 36)

      street where event is incidented

    - house_number: (string - maxLength: 36)

      house number where event is incidented

    - geo_position: (object)

      geo position specified by geographic coordinates - longitude and latitude

      - longitude: required(number - minimum: -180 - maximum: 180)

        longitude in degrees

      - latitude: required(number - minimum: -90 - maximum: 90)

        latitude in degrees

  - video_info: required(object)

    stream source video info

    - width: required(integer)

      stream source video width

    - height: required(integer)

      stream source video height

    - frame_rate: required(integer)

      stream source video frame rate

    - bit_rate: required(integer)

      stream source video bit rate

    - gop_size: required(integer)

      stream source video gop size

    - start_time: required(string)

      stream start time (ISO 8601)

- stream_info_v1

  - account_id: required(string)

    new stream account ID for authentication in Luna Platform

  - stream_id: required(string)

    stream UUID

  - name: required(string)

    display name

  - description: (string)

    new stream description

  - preview_url: required(string)

    stream preview URL

  - status: required(string)

    stream status

  - version: required(integer)

    stream version

  - error: required(string)

    stream error

  - data: required(object)

    stream input parameters

    - reference: required(string)

      camera address, e.g.

    - type: required(one of tcp, udp, videofile, images)

      transport protocol for rtsp camera, by default "tcp"

    - roi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - droi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - rotation: (integer)

      angle of camera frame rotation, possible values are 0, 90, 180, 270, by default 0

    - preferred_program_stream_frame_width: (integer)

      frame width of the preferred program stream, by default 800

    - endless: (boolean)

      determines if stream is endless

  - event_handler: required(object)

    stream event handler data

    - origin: required(string)

      event handler service origin

    - api_version: required(integer)

      event handler service api version

    - bestshot_handler: required(object)

      event bestshot handler

      - handler_id: required(string)

        handler id in Luna Platform

    - detection_handler: (object)

      event detection handler

      - handler_id: required(string)

        handler id in Luna Platform

    - frame_store: (string)

      frame store URL

  - policies: required(object)

    stream processing policies

    - ffmpeg_threads_number: required(integer)

      number of threads for video decoding, by default 0 - chosen by decoder library

    - frame_processing_mode: required(one of auto, full, scale)

      determines whether full or scaled frame will be processed, by default "auto" - depends on FACE_STREAM_CONFIG param 'convertFullFrame'

    - real_time_mode_fps: required(integer)

      the video is processed with the specified number of FPS. The video can’t be processed with FPS higher than the one specified in this parameter

    - health_check: required(object)

      stream health check parameters

      - max_error_count: (integer)

        error count limit in period to consider stream to be alive, by default 10

      - period: (integer)

        see description of max_error_count, measured in seconds, by default 3600

      - retry_delay: (integer)

        time gap (in seconds) between attempts to reopen not alive stream, by default 5

      - timeout: (integer)

        timeout in milliseconds that is set to read the encoded packet

    - filtering: required(object)

      stream filtering parameters

      - min_score_face: (number)

        score that defines face detection quality, threshold for filtering detections sent to the server, by default 0.5187.

      - min_score_body: (number)

        score that defines body detection quality, threshold for filtering detections sent to the server, by default 0.5.

      - min_body_size_threshold: (number)

        body detection size, less than which it will not be sent for processing, by default 0 (filtering by size is disabled).

      - detection_yaw_threshold: (integer)

        sets the maximum value of head yaw angle in relation to camera, by default 40.

      - detection_pitch_threshold: (integer)

        sets the maximum value of head pitch angle in relation to camera, by default 40.

      - detection_roll_threshold: (integer)

        sets the maximum value of head roll angle in relation to camera, by default 30.

      - yaw_number: (integer)

        defines the number of frames for image filtration based on head tilt angle, by default 1.

      - yaw_collection_mode: (boolean)

        sets the number of frames the system must collect to analyze head yaw angle, by default false.

      - mouth_occlusion_threshold: (number)

        determines how much the mouth can be obscured in the frame, by default 0.0.

    - sending: required(object)

      stream sending parameters

      - time_period_of_searching: required(integer)

        interval in track after the end of which a best shot is sent to the server, by default -1.

      - silent_period: required(integer)

        interval between period. Once the analysis period is over, the system holds this silent_period before starting next period of frame analysis, by default -1.

      - type: required(string)

        sets the measurement metric for analysis periods and intervals between those (per frames or per seconds), by default "sec".

      - number_of_bestshots_to_send: required(integer)

        number of frames that the user sets to receive from the track or certain periods of this track, by default 1.

      - send_only_full_set: required(boolean)

        This parameter enables to send data only if the required amount of data is available.

      - delete_track_after_sending: required(boolean)

        This parameter enables to delete track after sending.

    - primary_track_policy: required(object)

      stream primary track policy parameters

      - use_primary_track_policy: (boolean)

        is used in cases of Access Control Systems (turnstiles/gates at the office/bank entrances) for easier control and face recognition implementation in a secured area, by default false.

      - best_shot_min_size: (integer)

        sets a minimal size for detections within Primary Track policy, by default 70.

      - best_shot_proper_size: (integer)

        sets the size of detection for Primary Track policy. When a detection reaches the defined value, track immediately sends all its best shots to the server, by default 140.

    - liveness: required(object)

      stream liveness parameters

      - use_mask_liveness_filtration: (boolean)

        enables checking the presence of a real person in the frame based on backgrounds, by default false.

      - use_flying_faces_liveness_filtration: (boolean)

        enables checking the presence of a real person in the frame based on the facial surrounding, by default false.

      - liveness_mode: (integer)

        enables to specify which frames from a track will undergo Liveness check. There are three options for selecting a frame

      - number_of_liveness_checks: (integer)

        enables to specify the number of frames to check for Liveness. The specified value is used in the liveness-mode parameter. By default 10.

      - liveness_threshold: (number)

        is used to define the presence of a real person in a frame. The system confirms that it is a real person in the frame, and not a photo, only if Liveness returned a value higher than the one specified in the parameter. By default 0.8.

      - livenesses_weights: (array of any)

        determines the involvement of each liveness check type (mask, and flying_faces) in the resulting estimation of the presence of a human face in the frame. By default [0.25, 0.75].

      - mask_backgrounds_count: (integer)

        the number of background frames that are used for the corresponding checks, by default 300.

  - location: (object)

    stream source location parameters

    - city: (string - maxLength: 36)

      city where event is incidented

    - area: (string - maxLength: 36)

      area where event is incidented

    - district: (string - maxLength: 36)

      district where event is incidented

    - street: (string - maxLength: 36)

      street where event is incidented

    - house_number: (string - maxLength: 36)

      house number where event is incidented

    - geo_position: (object)

      geo position specified by geographic coordinates - longitude and latitude

      - longitude: required(number - minimum: -180 - maximum: 180)

        longitude in degrees

      - latitude: required(number - minimum: -90 - maximum: 90)

        latitude in degrees

  - video_info: required(object)

    stream source video info

    - width: required(integer)

      stream source video width

    - height: required(integer)

      stream source video height

    - frame_rate: required(integer)

      stream source video frame rate

    - bit_rate: required(integer)

      stream source video bit rate

    - gop_size: required(integer)

      stream source video gop size

    - start_time: required(string)

      stream start time (ISO 8601)

Example:

    [
      {
        "account_id": "f4aa8f0e-307a-464b-9f5f-0d1a4d1bc483",
        "data": {
          "analytics": [
            {
              "droi": {
                "height": 0,
                "mode": "abs",
                "width": 0,
                "x": 0,
                "y": 0
              },
              "enabled": true,
              "event_handler": {
                "authorization": {
                  "account_id": "f4aa8f0e-307a-464b-9f5f-0d1a4d1bc483"
                },
                "frame_store": "http://127.0.0.1:5020/1/buckets/frames/images",
                "handler_id": "ee4c42b6-23ae-410e-a2aa-a4220e64ba4b",
                "type": "luna_handler"
              },
              "filtering": {
                "detection_pitch_threshold": 40,
                "detection_roll_threshold": 30,
                "detection_yaw_threshold": 40,
                "min_body_size_threshold": 0,
                "min_score_body": 0.5,
                "min_score_face": 0.5187000036239624,
                "mouth_occlusion_threshold": 0,
                "yaw_collection_mode": false,
                "yaw_number": 1
              },
              "healthcheck": {
                "max_error_count": 10,
                "period": 3600,
                "retry_delay": 5,
                "timeout": 30000
              },
              "liveness": {
                "liveness_mode": 1,
                "liveness_threshold": 0.6000000238418579,
                "livenesses_weights": [
                  0.25,
                  0.75
                ],
                "mask_backgrounds_count": 300,
                "number_of_liveness_checks": 10,
                "use_flying_faces_liveness_filtration": false,
                "use_mask_liveness_filtration": false
              },
              "mode": 1,
              "primary_track_policy": {
                "best_shot_min_size": 70,
                "best_shot_proper_size": 140,
                "use_primary_track_policy": false
              },
              "sending": {
                "bestshot_settings": {
                  "body_bestshots_to_send": 1,
                  "face_bestshots_to_send": 1,
                  "type": 3
                },
                "body": {
                  "delete_track_after_sending": true,
                  "send_only_full_set": true
                },
                "full_frame_settings": 3,
                "silent_period": 0,
                "time_period_of_searching": -1,
                "type": "sec"
              }
            }
          ],
          "endless": true,
          "ffmpeg_threads_number": 0,
          "frame_processing_mode": "auto",
          "real_time_mode_fps": 0,
          "reference": "rtsp://127.0.0.1/video",
          "roi": {
            "height": 0,
            "mode": "abs",
            "width": 0,
            "x": 0,
            "y": 0
          },
          "rotation": 0,
          "preferred_program_stream_frame_width": 800,
          "type": "udp"
        },
        "description": "",
        "error": "ok",
        "location": {
          "area": "Central",
          "city": "Moscow",
          "district": "Basmanny",
          "geo_position": {
            "latitude": 55.752,
            "longitude": 36.616
          },
          "house_number": "23 bldg.3",
          "street": "Podsosensky lane"
        },
        "name": "Source 0",
        "preview_url": "/api/1/streams/preview/3d001360-d6df-40c7-97e9-2e0e4dc90edc",
        "status": "in_progress",
        "stream_id": "3d001360-d6df-40c7-97e9-2e0e4dc90edc",
        "version": 1,
        "video_info": {
          "duration": 0,
          "bit_rate": 0,
          "frame_rate": 25,
          "gop_size": 12,
          "height": 1080,
          "start_time": "2022-03-22T14:28:23.997Z",
          "width": 1920
        }
      }
    ]

## HTTP status code 400

Invalid query.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Any streams are not found"
    }

#### /streams/{id} get

get

Get stream info.

#### get /streams/{id}

Get stream info.

### URI Parameters

- id: required(string)

  Stream ID UUID.

## HTTP status code 200

Ok.

### Body

Media type: application/json

Possible types:

- stream_info_v2

  - account_id: required(string)

    new stream account ID for authentication in Luna Platform

  - stream_id: required(string)

    stream UUID

  - name: required(string)

    display name

  - description: (string)

    new stream description

  - preview_url: required(string)

    stream preview URL

  - status: required(string)

    stream status

  - version: required(integer)

    stream version

  - error: required(string)

    stream error

  - data: required(object)

    stream input parameters

    - analytics: required(array of analytics)

      Items: analytics

      - enabled: (boolean)

        determines if analytics is enabled

      - mode: (one of 1, 2, 3, 4)

        analytics mode 1 - "faces", 2 - "bodies", 3 - "humans", 4 - "fighting", by default 3 - "humans"

      - droi: (object)

        region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

        - x: required(number)

          x coordinate

        - y: required(number)

          y coordinate

        - width: required(number)

          width

        - height: required(number)

          height

        - mode: required(one of abs, percent)

          coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

      - event_handler: required(object)

        parameters related to sending the best shots to Luna Platform and processing them using handlers

        - type: (string)

          handler type, by default "luna_handler"

        - handler_id: required(string)

          handler id in Luna Platform

        - frame_store: (string)

          frame store URL

        - authorization: required(object)

          authorization for requests to the Luna API service of the Luna Platform

          - token: required(string)
      - filtering: (object)

        stream filtering parameters

        - min_score_face: (number)

          score that defines face detection quality, threshold for filtering detections sent to the server, by default 0.5187.

        - min_score_body: (number)

          score that defines body detection quality, threshold for filtering detections sent to the server, by default 0.5.

        - min_body_size_threshold: (number)

          body detection size, less than which it will not be sent for processing, by default 0 (filtering by size is disabled).

        - detection_yaw_threshold: (integer)

          sets the maximum value of head yaw angle in relation to camera, by default 40.

        - detection_pitch_threshold: (integer)

          sets the maximum value of head pitch angle in relation to camera, by default 40.

        - detection_roll_threshold: (integer)

          sets the maximum value of head roll angle in relation to camera, by default 30.

        - yaw_number: (integer)

          defines the number of frames for image filtration based on head tilt angle, by default 1.

        - yaw_collection_mode: (boolean)

          sets the number of frames the system must collect to analyze head yaw angle, by default false.

        - mouth_occlusion_threshold: (number)

          determines how much the mouth can be obscured in the frame, by default 0.0.

      - liveness: (object)

        stream liveness parameters

        - use_mask_liveness_filtration: (boolean)

          enables checking the presence of a real person in the frame based on backgrounds, by default false.

        - use_flying_faces_liveness_filtration: (boolean)

          enables checking the presence of a real person in the frame based on the facial surrounding, by default false.

        - liveness_mode: (integer)

          enables to specify which frames from a track will undergo Liveness check. There are three options for selecting a frame

        - number_of_liveness_checks: (integer)

          enables to specify the number of frames to check for Liveness. The specified value is used in the liveness-mode parameter. By default 10.

        - liveness_threshold: (number)

          is used to define the presence of a real person in a frame. The system confirms that it is a real person in the frame, and not a photo, only if Liveness returned a value higher than the one specified in the parameter. By default 0.8.

        - livenesses_weights: (array of any)

          determines the involvement of each liveness check type (mask, and flying_faces) in the resulting estimation of the presence of a human face in the frame. By default [0.25, 0.75].

        - mask_backgrounds_count: (integer)

          the number of background frames that are used for the corresponding checks, by default 300.

      - primary_track_policy: (object)

        stream primary track policy parameters

        - use_primary_track_policy: (boolean)

          is used in cases of Access Control Systems (turnstiles/gates at the office/bank entrances) for easier control and face recognition implementation in a secured area, by default false.

        - best_shot_min_size: (integer)

          sets a minimal size for detections within Primary Track policy, by default 70.

        - best_shot_proper_size: (integer)

          sets the size of detection for Primary Track policy. When a detection reaches the defined value, track immediately sends all its best shots to the server, by default 140.

      - sending: (object)

        stream sending parameters

        - time_period_of_searching: (integer)

          interval in track after the end of which a best shot is sent to the server, by default -1.

        - silent_period: (integer)

          interval between period. Once the analysis period is over, the system holds this silent_period before starting next period of frame analysis, by default -1.

        - type: (string)

          sets the measurement metric for analysis periods and intervals between those (per frames or per seconds), by default "sec".

        - bestshot_settings: (object)

          settings of which bestshots will be sent to platform

          - face_bestshots_to_send: (integer)

            number of face frames that the user sets to receive from the track or certain periods of this track, by default 1.

          - body_bestshots_to_send: (integer)

            number of body frames that the user sets to receive from the track or certain periods of this track, by default 1.

          - type: (one of 1, 2, 3, 4)

            bestshot mode 1 - "faces_only", 2- "bodies_only", 3 - "faces_with_bodies", 4 - "separately", by default 3 - "faces_with_bodies"

        - body: (object)

          body periodic sending settings

          - send_only_full_set: (boolean)

            send data only if the required number of best shots and detections have been collected, by default true.

          - delete_track_after_sending: (boolean)

            whether to delete the best shots and detections after sending the data, by default false.

        - full_frame_settings: (one of 1, 2, 3, 4)

          defines which source frames will be sent to Luna Platform 1 - "faces_only", 2- "bodies_only", 3 - "faces_with_bodies", 4 - "separately", by default 3 - "faces_with_bodies"

      - healthcheck: (object)

        stream health check parameters

        - max_error_count: (integer)

          error count limit in period to consider stream to be alive, by default 10

        - period: (integer)

          see description of max_error_count, measured in seconds, by default 3600

        - retry_delay: (integer)

          time gap (in seconds) between attempts to reopen not alive stream, by default 5

        - timeout: (integer)

          timeout in milliseconds that is set to read the encoded packet

    - ffmpeg_threads_number: (integer)

      number of threads for video decoding, by default 0 - chosen by decoder library

    - frame_processing_mode: (one of auto, full, scale)

      determines whether full or scaled frame will be processed, by default "auto" - depends on FACE_STREAM_CONFIG param 'convertFullFrame'

    - real_time_mode_fps: required(integer)

      the video is processed with the specified number of FPS. The video can’t be processed with FPS higher than the one specified in this parameter

    - reference: required(string)

      camera address, e.g.

    - type: required(one of tcp, udp, videofile, images)

      transport protocol for rtsp camera, by default "tcp"

    - roi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - rotation: (integer)

      angle of camera frame rotation, possible values are 0, 90, 180, 270, by default 0

    - preferred_program_stream_frame_width: (integer)

      frame width of the preferred program stream, by default 800

    - endless: (boolean)

      determines if stream is endless

  - location: (object)

    stream source location parameters

    - city: (string - maxLength: 36)

      city where event is incidented

    - area: (string - maxLength: 36)

      area where event is incidented

    - district: (string - maxLength: 36)

      district where event is incidented

    - street: (string - maxLength: 36)

      street where event is incidented

    - house_number: (string - maxLength: 36)

      house number where event is incidented

    - geo_position: (object)

      geo position specified by geographic coordinates - longitude and latitude

      - longitude: required(number - minimum: -180 - maximum: 180)

        longitude in degrees

      - latitude: required(number - minimum: -90 - maximum: 90)

        latitude in degrees

  - video_info: required(object)

    stream source video info

    - width: required(integer)

      stream source video width

    - height: required(integer)

      stream source video height

    - frame_rate: required(integer)

      stream source video frame rate

    - bit_rate: required(integer)

      stream source video bit rate

    - gop_size: required(integer)

      stream source video gop size

    - start_time: required(string)

      stream start time (ISO 8601)

- stream_info_v1

  - account_id: required(string)

    new stream account ID for authentication in Luna Platform

  - stream_id: required(string)

    stream UUID

  - name: required(string)

    display name

  - description: (string)

    new stream description

  - preview_url: required(string)

    stream preview URL

  - status: required(string)

    stream status

  - version: required(integer)

    stream version

  - error: required(string)

    stream error

  - data: required(object)

    stream input parameters

    - reference: required(string)

      camera address, e.g.

    - type: required(one of tcp, udp, videofile, images)

      transport protocol for rtsp camera, by default "tcp"

    - roi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - droi: (object)

      region of interest of camera frame (left, top, width, height), by default [0 0 0 0] - full frame

      - x: required(number)

        x coordinate

      - y: required(number)

        y coordinate

      - width: required(number)

        width

      - height: required(number)

        height

      - mode: required(one of abs, percent)

        coordinates mode, "abs" - absolute coordinates and size in pixels, "percent" - coordinates and size are set by percents of stream image size

    - rotation: (integer)

      angle of camera frame rotation, possible values are 0, 90, 180, 270, by default 0

    - preferred_program_stream_frame_width: (integer)

      frame width of the preferred program stream, by default 800

    - endless: (boolean)

      determines if stream is endless

  - event_handler: required(object)

    stream event handler data

    - origin: required(string)

      event handler service origin

    - api_version: required(integer)

      event handler service api version

    - bestshot_handler: required(object)

      event bestshot handler

      - handler_id: required(string)

        handler id in Luna Platform

    - detection_handler: (object)

      event detection handler

      - handler_id: required(string)

        handler id in Luna Platform

    - frame_store: (string)

      frame store URL

  - policies: required(object)

    stream processing policies

    - ffmpeg_threads_number: required(integer)

      number of threads for video decoding, by default 0 - chosen by decoder library

    - frame_processing_mode: required(one of auto, full, scale)

      determines whether full or scaled frame will be processed, by default "auto" - depends on FACE_STREAM_CONFIG param 'convertFullFrame'

    - real_time_mode_fps: required(integer)

      the video is processed with the specified number of FPS. The video can’t be processed with FPS higher than the one specified in this parameter

    - health_check: required(object)

      stream health check parameters

      - max_error_count: (integer)

        error count limit in period to consider stream to be alive, by default 10

      - period: (integer)

        see description of max_error_count, measured in seconds, by default 3600

      - retry_delay: (integer)

        time gap (in seconds) between attempts to reopen not alive stream, by default 5

      - timeout: (integer)

        timeout in milliseconds that is set to read the encoded packet

    - filtering: required(object)

      stream filtering parameters

      - min_score_face: (number)

        score that defines face detection quality, threshold for filtering detections sent to the server, by default 0.5187.

      - min_score_body: (number)

        score that defines body detection quality, threshold for filtering detections sent to the server, by default 0.5.

      - min_body_size_threshold: (number)

        body detection size, less than which it will not be sent for processing, by default 0 (filtering by size is disabled).

      - detection_yaw_threshold: (integer)

        sets the maximum value of head yaw angle in relation to camera, by default 40.

      - detection_pitch_threshold: (integer)

        sets the maximum value of head pitch angle in relation to camera, by default 40.

      - detection_roll_threshold: (integer)

        sets the maximum value of head roll angle in relation to camera, by default 30.

      - yaw_number: (integer)

        defines the number of frames for image filtration based on head tilt angle, by default 1.

      - yaw_collection_mode: (boolean)

        sets the number of frames the system must collect to analyze head yaw angle, by default false.

      - mouth_occlusion_threshold: (number)

        determines how much the mouth can be obscured in the frame, by default 0.0.

    - sending: required(object)

      stream sending parameters

      - time_period_of_searching: required(integer)

        interval in track after the end of which a best shot is sent to the server, by default -1.

      - silent_period: required(integer)

        interval between period. Once the analysis period is over, the system holds this silent_period before starting next period of frame analysis, by default -1.

      - type: required(string)

        sets the measurement metric for analysis periods and intervals between those (per frames or per seconds), by default "sec".

      - number_of_bestshots_to_send: required(integer)

        number of frames that the user sets to receive from the track or certain periods of this track, by default 1.

      - send_only_full_set: required(boolean)

        This parameter enables to send data only if the required amount of data is available.

      - delete_track_after_sending: required(boolean)

        This parameter enables to delete track after sending.

    - primary_track_policy: required(object)

      stream primary track policy parameters

      - use_primary_track_policy: (boolean)

        is used in cases of Access Control Systems (turnstiles/gates at the office/bank entrances) for easier control and face recognition implementation in a secured area, by default false.

      - best_shot_min_size: (integer)

        sets a minimal size for detections within Primary Track policy, by default 70.

      - best_shot_proper_size: (integer)

        sets the size of detection for Primary Track policy. When a detection reaches the defined value, track immediately sends all its best shots to the server, by default 140.

    - liveness: required(object)

      stream liveness parameters

      - use_mask_liveness_filtration: (boolean)

        enables checking the presence of a real person in the frame based on backgrounds, by default false.

      - use_flying_faces_liveness_filtration: (boolean)

        enables checking the presence of a real person in the frame based on the facial surrounding, by default false.

      - liveness_mode: (integer)

        enables to specify which frames from a track will undergo Liveness check. There are three options for selecting a frame

      - number_of_liveness_checks: (integer)

        enables to specify the number of frames to check for Liveness. The specified value is used in the liveness-mode parameter. By default 10.

      - liveness_threshold: (number)

        is used to define the presence of a real person in a frame. The system confirms that it is a real person in the frame, and not a photo, only if Liveness returned a value higher than the one specified in the parameter. By default 0.8.

      - livenesses_weights: (array of any)

        determines the involvement of each liveness check type (mask, and flying_faces) in the resulting estimation of the presence of a human face in the frame. By default [0.25, 0.75].

      - mask_backgrounds_count: (integer)

        the number of background frames that are used for the corresponding checks, by default 300.

  - location: (object)

    stream source location parameters

    - city: (string - maxLength: 36)

      city where event is incidented

    - area: (string - maxLength: 36)

      area where event is incidented

    - district: (string - maxLength: 36)

      district where event is incidented

    - street: (string - maxLength: 36)

      street where event is incidented

    - house_number: (string - maxLength: 36)

      house number where event is incidented

    - geo_position: (object)

      geo position specified by geographic coordinates - longitude and latitude

      - longitude: required(number - minimum: -180 - maximum: 180)

        longitude in degrees

      - latitude: required(number - minimum: -90 - maximum: 90)

        latitude in degrees

  - video_info: required(object)

    stream source video info

    - width: required(integer)

      stream source video width

    - height: required(integer)

      stream source video height

    - frame_rate: required(integer)

      stream source video frame rate

    - bit_rate: required(integer)

      stream source video bit rate

    - gop_size: required(integer)

      stream source video gop size

    - start_time: required(string)

      stream start time (ISO 8601)

Example:

    {
      "account_id": "f4aa8f0e-307a-464b-9f5f-0d1a4d1bc483",
      "data": {
        "analytics": [
          {
            "droi": {
              "height": 0,
              "mode": "abs",
              "width": 0,
              "x": 0,
              "y": 0
            },
            "enabled": true,
            "event_handler": {
              "authorization": {
                "account_id": "f4aa8f0e-307a-464b-9f5f-0d1a4d1bc483"
              },
              "frame_store": "http://127.0.0.1:5020/1/buckets/frames/images",
              "handler_id": "ee4c42b6-23ae-410e-a2aa-a4220e64ba4b",
              "type": "luna_handler"
            },
            "filtering": {
              "detection_pitch_threshold": 40,
              "detection_roll_threshold": 30,
              "detection_yaw_threshold": 40,
              "min_body_size_threshold": 0,
              "min_score_body": 0.5,
              "min_score_face": 0.5187000036239624,
              "mouth_occlusion_threshold": 0,
              "yaw_collection_mode": false,
              "yaw_number": 1
            },
            "healthcheck": {
              "max_error_count": 10,
              "period": 3600,
              "retry_delay": 5,
              "timeout": 30000
            },
            "liveness": {
              "liveness_mode": 1,
              "liveness_threshold": 0.6000000238418579,
              "livenesses_weights": [
                0.25,
                0.75
              ],
              "mask_backgrounds_count": 300,
              "number_of_liveness_checks": 10,
              "use_flying_faces_liveness_filtration": false,
              "use_mask_liveness_filtration": false
            },
            "mode": 1,
            "primary_track_policy": {
              "best_shot_min_size": 70,
              "best_shot_proper_size": 140,
              "use_primary_track_policy": false
            },
            "sending": {
              "bestshot_settings": {
                "body_bestshots_to_send": 1,
                "face_bestshots_to_send": 1,
                "type": 3
              },
              "body": {
                "delete_track_after_sending": true,
                "send_only_full_set": true
              },
              "full_frame_settings": 3,
              "silent_period": 0,
              "time_period_of_searching": -1,
              "type": "sec"
            }
          }
        ],
        "endless": true,
        "ffmpeg_threads_number": 0,
        "frame_processing_mode": "auto",
        "real_time_mode_fps": 0,
        "reference": "rtsp://127.0.0.1/video",
        "roi": {
          "height": 0,
          "mode": "abs",
          "width": 0,
          "x": 0,
          "y": 0
        },
        "rotation": 0,
        "type": "udp"
      },
      "description": "",
      "error": "ok",
      "location": {
        "area": "Central",
        "city": "Moscow",
        "district": "Basmanny",
        "geo_position": {
          "latitude": 55.752,
          "longitude": 36.616
        },
        "house_number": "23 bldg.3",
        "street": "Podsosensky lane"
      },
      "name": "Source 0",
      "preview_url": "/api/1/streams/preview/3d001360-d6df-40c7-97e9-2e0e4dc90edc",
      "status": "in_progress",
      "stream_id": "3d001360-d6df-40c7-97e9-2e0e4dc90edc",
      "version": 1,
      "video_info": {
        "duration": 0,
        "bit_rate": 0,
        "frame_rate": 25,
        "gop_size": 12,
        "height": 1080,
        "start_time": "2022-03-22T14:28:23.997Z",
        "width": 1920
      }
    }

## HTTP status code 400

Invalid query or JSON.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Invalid uuid"
    }

## HTTP status code 404

Stream not found.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Stream with such uuid doesn't exist"
    }

## HTTP status code 500

Internal error.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 2,
      "detail": "Unhandled exception"
    }

#### /streams/preview/{id} get

get

Allows clients to obtain stream preview as MotionJPEG: server sends JPEG stream of frames.

#### get /streams/preview/{id}

Allows clients to obtain stream preview as MotionJPEG: server sends JPEG stream of frames.

### URI Parameters

- id: required(string)

  Stream UUID.

### Query Parameters

- quality: (integer)

  JPEG compression level of stream preview image (is in [0, 100] range, values lower than 25 could produce bad visual quality), by default 75

- show_bbox: (integer)

  Show tracks and some other info on stream preview (0 or 1), by default 1

- width: (integer)

  Max preview width (scaled down if actual width is larger). Image is scaled with proportion saving. If it is equal 0, doesn't affect, by default 0

- height: (integer)

  Max preview height (scaled down if actual height is larger). Image is scaled with proportion saving. If it is equal 0, doesn't affect, by default 0

- fps: (integer)

  Max translation stream fps. If it is equal 0, doesn't affect, by default 0

## HTTP status code 200

Ok.

### Body

Media type: image/jpeg

Type: any

Example:

    <jpeg image data>

## HTTP status code 400

Invalid query or id.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Invalid uuid"
    }

## HTTP status code 404

Stream not found.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Stream with such uuid doesn't exist"
    }

## HTTP status code 500

Internal error.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 2,
      "detail": "Unhandled exception"
    }

#### /streams/preview/frame/{id} get

get

Gets stream last frame as image/jpeg.

#### get /streams/preview/frame/{id}

Gets stream last frame as image/jpeg.

### URI Parameters

- id: required(string)

  Stream UUID.

### Query Parameters

- quality: (integer)

  JPEG compression level of stream preview image (is in [0, 100] range, values lower than 25 could produce bad visual quality), by default 75

## HTTP status code 200

Ok.

### Body

Media type: image/jpeg

Type: any

Example:

    <jpeg image data>

## HTTP status code 400

Invalid query or id.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Invalid uuid"
    }

## HTTP status code 404

Stream not found.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 1,
      "detail": "Stream with such uuid doesn't exist"
    }

## HTTP status code 500

Internal error.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 2,
      "detail": "Failed to encode frame to jpeg"
    }

### /metrics

Stream API allows clients to get all metrics about Face Stream's current state, like streams or translations count, errors, etc.

Output format can be obtained from "https://prometheus.io/".

Metrics is subdivided into two sections: global metrics (all streams information) and each stream's metrics.

Global metrics section is started with comment "# Global counters".

Each stream metrics section is started with comment like "# Stream name = 'stream name' uuid = 'stream uuid'".

Global metrics counters:

Create_stream_errors - streams creating errors counter. Tags: "code" (text code of error) and "msg" (description of error)

Streams_count - current streams count. Tags: "all" (all streams count) and "alive" (alive streams count)

Translations_count - current translations count

Streams metrics counters:

Streams_errors - count of errors occurred in attempts to open stream or read frame from it. Tags: "action" (open or read frame), "error" (text code of error), "msg" (description of error)

Skips_count - total frames, that have been skipped (not processed) because of high load

Detections_count - current frame detections count

FPS - current FPS (of stream processing)

#### /metrics get

get

Allows clients to obtain metrics about streams.

#### get /metrics

Allows clients to obtain metrics about streams.

## HTTP status code 200

Ok.

### Body

Media type: text/plain

Type: any

## HTTP status code 500

Internal error.

### Body

Media type: application/json

Type: any

Example:

    {
      "error_code": 2,
      "detail": "Unhandled exception"
    }

### /version

Receiving version information about FaceStream.

#### /version get

get

Receiving version information about FaceStream.

#### get /version

Receiving version information about FaceStream.

## HTTP status code 200

Ok.

### Body

Media type: application/json

Type: any

Example:

    {
      "FaceStream": {
        "api": 1,
        "major": 5,
        "minor": 0,
        "patch": 6
      },
      "LunaSDK": {
        "major": 5,
        "minor": 16,
        "patch": 1
      }
    }