FaceStream version 5.2.3

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"
}

URI Parameters

• id: required(string)

  Stream ID UUID.

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

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: text/plain

Type: any

HTTP status code 500

Internal error.

Body

Media type: application/json

Type: any

Example:

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

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
  }
}