.. _api_videos:


Videos
========================

.. _list_video_archives:

List video archives
-----------------------

To list video archives, use the following method:

.. code::

    GET /videos/

The REQUEST contains the following QUERY-STRING PARAMETERS:

.. _video_request_parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name
       - Type
       - Description
     * - ``camera_groups``
       - array of integers
       - Select video archives included in the camera groups with the specified IDs.
     * - ``case_in``
       - array of integers
       - Select video archives included in the cases with the specified IDs.
     * - ``created_date_gt``
       - date-time
       - Select video archives with ``created_date`` greater than the specified value.
     * - ``created_date_gte``
       - date-time
       - Select video archives with ``created_date`` greater than or equal to the specified value.
     * - ``created_date_last_n_days``
       - number
       - Select video archives with ``created_date`` in the last N days.
     * - ``created_date_lt``
       - date-time
       - Select video archives with ``created_date`` less than the specified value.
     * - ``created_date_lte``
       - date-time
       - Select video archives with ``created_date`` less than or equal to the specified value.
     * - ``created_date_nth_full_week``
       - number
       - Select video archives with ``created_date`` in the last N weeks (including Sunday and Saturday).
     * - ``created_date_nth_work_week``
       - number
       - Select video archives with ``created_date`` in the last N weeks (only working days, i.e. excluding Sunday and Saturday).
     * - ``id_in``
       - array of integers
       - Select video archives with the specified IDs.
     * - ``limit``
       - integer
       - Number of results to return per page.
     * - ``name_contains``
       - string
       - Select video archives whose name contains the specified text, regardless of case.
     * - ``ordering``
       - string
       - Field for sorting the request results. Available fields: ``id``, ``created_date``, ``name``.
     * - ``page``
       - string
       - Pagination cursor value.

For example, specify the value of the ``limit`` parameter to restrict the number of results per page.

.. rubric:: CURL example

.. code::

 curl -X GET "http://<findface-ip:port>/videos/?limit=2" \
  -H "Authorization: Token <token>"

If the response is successful (OK: 200), it returns a JSON object that contains the following parameters:

.. list-table::
     :widths: 16 10 45
     :header-rows: 1

     * - Name
       - Type
       - Description
     * - ``next_page``
       - string┃null
       - Next page.
     * - ``prev_page``
       - string┃null
       - Previous page.
     * - ``results``
       - [{...}]
       - Array containing :ref:`the following parameters <result_parameters>`. :ref:`Example <get_video_response_example>`.

.. note::

  `*` – means required parameters. 🆁 – read only.

.. _result_parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name
       - Type
       - Description
     * - ``id*``
       - integer 🆁
       - Video archive ID.
     * - ``camera_group*``
       - integer
       - Camera group ID.
     * - ``name*``
       - string┃null
       - Name of the video archive. 
        
         Constraints: Min 1┃Max 256 chars.
     * - ``url``
       - string┃null
       - URL of the source video file.
     * - ``camera``
       - integer┃null
       - Camera ID.
     * - ``processing_start_date*``
       - date-time 🆁
       - Timestamp indicating when the video processing started.
     * - ``active*``
       - boolean 🆁
       - ``true`` if the video processing is active.
     * - ``router_url``
       - string┃null
       - URL for sending detected objects from ``findface-video-worker`` to an external component for further processing.
     * - ``screenshot*``
       - uri 🆁
       - Screenshot URL.
     * - ``stream_settings``
       - object
       - Settings of video processing parameters, including:

	      - detector settings for processing and tracking specific types of objects (such as faces, bodies, and vehicles) from the video stream;
	      - general video stream settings such as play speed limit (``play_speed``), minimum motion intensity (``imotion_threshold``), timestamp source (``use_stream_timestamp``, ``use_rtsp_time``), and more.
     * - ``source_len*``
       - number 🆁
       - Source length in seconds.
     * - ``health_status*``
       - object
       - Contains information about video processing: 
        
          - enabled state (``enabled``);
          - processing status (``status``);
          - statistics (``statistic``).  
        
         The object also includes additional data for displaying in the UI (``code``, ``code_desc``).
     * - ``finished*``
       - boolean 🆁
       - ``true`` if the video processing is finished.
     * - ``queued*``
       - boolean 🆁
       - ``true`` if the video is in the processing queue.
     * - ``face_count*``
       - integer 🆁
       - Number of created faces.
     * - ``file_size*``
       - integer 🆁
       - Video file size in the archive.
     * - ``created_date*``
       - date-time 🆁
       - Video archive creation date.
     * - ``body_count*``
       - integer 🆁
       - Number of created bodies.
     * - ``car_count*``
       - integer 🆁
       - Number of created vehicles.
     * - ``case``
       - integer┃null
       - Case ID.
     * - ``face_cluster_count*``
       - integer┃null 🆁
       - Number of face clusters created from this video.
     * - ``body_cluster_count*``
       - integer┃null 🆁
       - Number of body clusters created from this video.
     * - ``car_cluster_count*``
       - integer┃null 🆁
       - Number of vehicle clusters created from this video.
     * - ``frame_height*``
       - integer 🆁
       - Original height of the frames (in pixels) from the video stream.
     * - ``frame_width*``
       - integer 🆁
       - Original width of the frames (in pixels) from the video stream.
     * - ``error*``
       - string 🆁
       - Error occurred while processing the video archive.

.. note::
   Cases are not supported in FindFace Multi 2.0+ and are kept in API only.

.. _get_video_response_example:

.. rubric:: Response example

.. code::

 {
  "next_page": null,
  "prev_page": null,
  "results": [
    {
      "id": 2,
      "camera_group": 1,
      "name": "file.mp4",
      "url": null,
      "camera": null,
      "processing_start_date": "2025-03-28T11:55:13.335020Z",
      "active": false,
      "router_url": null,
      "screenshot": "http://<findface-ip:port>/videos/2/screenshot/",
      "stream_settings": {
        "detectors": {
          "face": {
            "filter_max_size": 8192,
            "filter_min_quality": 0.42,
            "filter_min_size": 60,
            "fullframe_crop_rot": false,
            "fullframe_use_png": false,
            "jpeg_quality": 95,
            "overall_only": true,
            "post_best_track_frame": true,
            "post_best_track_normalize": true,
            "post_first_track_frame": false,
            "post_last_track_frame": false,
            "realtime_post_every_interval": false,
            "realtime_post_first_immediately": false,
            "realtime_post_interval": 1,
            "roi": "",
            "track_interpolate_bboxes": true,
            "track_max_duration_frames": 0,
            "track_miss_interval": 1,
            "track_overlap_threshold": 0.25,
            "track_send_history": false,
            "tracker_type": "simple_iou",
            "track_deep_sort_matching_threshold": 0.65,
            "track_deep_sort_filter_unconfirmed_tracks": true,
            "filter_track_min_duration_frames": 1
          },
          "body": null,
          "car": null
        },
        "disable_drops": true,
        "ffmpeg_format": "",
        "ffmpeg_params": [],
        "imotion_threshold": 0,
        "play_speed": -1,
        "rot": "",
        "router_timeout_ms": 15000,
        "router_verify_ssl": true,
        "start_stream_timestamp": 0,
        "stream_data_filter": "",
        "use_stream_timestamp": false,
        "video_transform": "",
        "enable_recorder": false,
        "enable_liveness": false,
        "record_audio": false,
        "use_rtsp_time": true
      },
      "source_len": 12.533333,
      "health_status": {
        "enabled": false,
        "status": "COMPLETED",
        "msg": "",
        "statistic": {
          "processed_duration": 12.466666,
          "faces_posted": 5,
          "faces_failed": 0,
          "faces_not_posted": 0,
          "processing_fps": 30.567686,
          "frames_dropped": 0,
          "frames_processed": 188,
          "frames_imotion_skipped": 0,
          "decoding_soft_errors": 4,
          "frame_width": 1154,
          "frame_height": 602,
          "last_stream_timestamp": 12.466666,
          "objects": {
            "face": {
              "posted": 5,
              "failed": 0,
              "not_posted": 0
            }
          },
          "extractors": {},
          "job_starts": 1
        },
        "code": "green",
        "code_desc": "Video processing is done"
      },
      "finished": true,
      "queued": false,
      "face_count": 6,
      "file_size": 2259950,
      "created_date": "2025-03-28T11:37:28.170028Z",
      "body_count": 0,
      "car_count": 0,
      "case": null,
      "face_cluster_count": 1,
      "body_cluster_count": 0,
      "car_cluster_count": 0,
      "frame_height": 602,
      "frame_width": 1154,
      "error": null
    }
  ]
 }

.. _add_a_new_video_archive:

Add a new video archive
---------------------------------

To add a video archive, use the following method:

.. code::

    POST /videos/

The REQUEST BODY is required and contains an application/json object with the following parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name
       - Type
       - Description
     * - ``camera_group*``
       - integer
       - Camera group ID.
     * - ``name*``
       - string┃null
       - Name of the video archive.
        
         Constraints: Min 1┃Max 256 chars.
     * - ``url``
       - string┃null
       - URL of the source video file to be uploaded. 
        
         Alternatively, you can use the ``PUT /videos/{id}/upload/source_file/`` method to upload the source video file.

         Constraint: Min 1 char.
     * - ``camera``
       - integer┃null
       - Camera ID.
     * - ``router_url``
       - string┃null
       - URL for sending detected objects from ``findface-video-worker`` to an external component for further processing.
     * - ``stream_settings``
       - object
       - Settings of video processing parameters, including:

	      - detector settings for processing and tracking specific types of objects (such as faces, bodies, and vehicles) from the video stream;
	      - general video stream settings such as play speed limit (``play_speed``), minimum motion intensity (``imotion_threshold``), timestamp source (``use_stream_timestamp``, ``use_rtsp_time``), and more.
     * - ``case``
       - integer┃null
       - Case ID.

.. note::
   Cases are not supported in FindFace Multi 2.0+ and are kept in API only.

.. rubric:: Request example

.. tip::

  This example is provided for reference only. Substitute your own values in the corresponding fields. You only need to fill in the required fields; all other fields will use their default values.

.. code::

 {
  "camera_group": 0,
  "name": "A",
  "url": "A",
  "camera": 0,
  "router_url": "string",
  "stream_settings": {
    "detectors": {
      "face": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      },
      "body": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      },
      "car": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      }
    },
    "disable_drops": false,
    "ffmpeg_format": "string",
    "ffmpeg_params": [
      "A"
    ],
    "imotion_threshold": 0,
    "play_speed": 0,
    "rot": "string",
    "router_timeout_ms": 0,
    "router_verify_ssl": false,
    "start_stream_timestamp": 0,
    "stream_data_filter": "string",
    "use_stream_timestamp": false,
    "video_transform": "string",
    "enable_recorder": false,
    "enable_liveness": false,
    "record_audio": false,
    "use_rtsp_time": false
  },
  "case": 0
 }

For example, you can send these parameters:

.. code::

 {
  "camera_group": 1,
  "name": "Pitt&Jolie"
 }

.. rubric:: CURL example

.. code::

 curl -X POST "http://<findface-ip:port>/videos/" \
   -H "Authorization: Token <token>" \
   -H "Content-Type: application/json" \
   -d '{"camera_group":1,"name":"Pitt&Jolie"}'

If the response is successful (Created: 201), it returns a JSON object that contains :ref:`parameters <result_parameters>`. :ref:`Example <post_video_response_example>`.

.. _post_video_response_example:

.. rubric:: Response example

.. code::

 {
  "id": 6,
  "camera_group": 1,
  "name": "Pitt&Jolie",
  "url": null,
  "camera": null,
  "processing_start_date": null,
  "active": false,
  "router_url": "string",
  "screenshot": "http://<findface-ip:port>/videos/6/screenshot/",
  "stream_settings": {
    "detectors": {
      "face": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      },
      "body": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      },
      "car": {
        "filter_max_size": 0,
        "filter_min_quality": 0,
        "filter_min_size": 0,
        "fullframe_crop_rot": false,
        "fullframe_use_png": false,
        "jpeg_quality": 0,
        "overall_only": false,
        "post_best_track_frame": false,
        "post_best_track_normalize": false,
        "post_first_track_frame": false,
        "post_last_track_frame": false,
        "realtime_post_every_interval": false,
        "realtime_post_first_immediately": false,
        "realtime_post_interval": 0,
        "roi": "string",
        "track_interpolate_bboxes": false,
        "track_max_duration_frames": 0,
        "track_miss_interval": 0,
        "track_overlap_threshold": 0,
        "track_send_history": false,
        "tracker_type": "string",
        "track_deep_sort_matching_threshold": 0,
        "track_deep_sort_filter_unconfirmed_tracks": false,
        "filter_track_min_duration_frames": 0
      }
    },
    "disable_drops": false,
    "ffmpeg_format": "string",
    "ffmpeg_params": [
      "A"
    ],
    "imotion_threshold": 0,
    "play_speed": 0,
    "rot": "string",
    "router_timeout_ms": 0,
    "router_verify_ssl": false,
    "start_stream_timestamp": 0,
    "stream_data_filter": "string",
    "use_stream_timestamp": false,
    "video_transform": "string",
    "enable_recorder": false,
    "enable_liveness": false,
    "record_audio": false,
    "use_rtsp_time": false
  },
  "source_len": null,
  "health_status": {
    "enabled": false,
    "status": "WAITING_FOR_SYNC",
    "msg": "",
    "statistic": {},
    "code": "red",
    "code_desc": "Videomanager job is missing. Wait for synchronization."
  },
  "finished": false,
  "queued": false,
  "face_count": 0,
  "file_size": 0,
  "created_date": "2025-03-28T14:26:35.641469Z",
  "body_count": 0,
  "car_count": 0,
  "case": null,
  "face_cluster_count": 0,
  "body_cluster_count": 0,
  "car_cluster_count": 0,
  "frame_height": null,
  "frame_width": null,
  "error": null
 }

Next, you can use the ``id`` of the added video archive to upload a video file via the ``PUT /videos/{id}/upload/source_file/`` method.

.. _attach_source_video_file:

Upload a video file
---------------------------------

To upload a video file, use the following method:

.. code::

    PUT /videos/{id}/upload/source_file/

The request contains the required PATH PARAMETER:

+----------------------------+---------------------------+--------------------------------------------------------------------------------+
| Name                       | Type                      | Description                                                                    |
+============================+===========================+================================================================================+
| ``id*``                    | integer                   | Unique integer identifier of the video archive.                                |
+----------------------------+---------------------------+--------------------------------------------------------------------------------+

In the REQUEST BODY, attach your source video file, with the video archive ``id`` specified in the URL path.

**Returns**:

* Created: 201 – on success.
* Not Found: 404 – on failure.

.. rubric:: CURL example

.. code::

  curl -X PUT "http://<findface-ip:port>/videos/6/upload/source_file/" \
   -H "Authorization: Token <token>" \
   -H "Content-Type: video/mp4" \
   --data-binary @sample.mp4 
 
.. tip::

  Replace ``sample.mp4`` with the full path if the video file is not in your current working directory.
  Example: ``--data-binary @"/home/ubuntu/sample.mp4"``

.. _start_video_archive_processing:

Start video archive processing
---------------------------------------

To start processing the video archive, use the following method:

.. code::

  POST /videos/{id}/process/

The REQUEST includes the ``id`` as the PATH PARAMETER. The specified ``id`` represents the unique integer identifier of the video archive.

.. rubric:: CURL example

.. code::

  curl -X POST "http://<findface-ip:port>/videos/6/process/" \
   -H "Authorization: Token <token>" 

**Returns**:

* OK: 200 – on success.
* Not Found: 404 – on failure.

Useful requests
---------------------------------

.. code::

  GET /videos/
  POST /videos/
  GET /videos/{id}/
  PUT /videos/{id}/
  DELETE /videos/{id}/
  PATCH /videos/{id}/
  DELETE /videos/{id}/file/
  POST /videos/{id}/process/
  GET /videos/{id}/screenshot/
  POST /videos/{id}/screenshot/
  POST /videos/{id}/stop/
  PUT /videos/{id}/upload/source_file/
  GET /videos/count/