Videos

List video archives

To list video archives, use the following method:

GET /videos/

The REQUEST contains the following QUERY-STRING PARAMETERS:

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.

CURL example

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:

Name	Type	Description
`next_page`	string┃null	Next page.
`prev_page`	string┃null	Previous page.
`results`	[{…}]	Array containing the following parameters. Example.

Note

* – means required parameters. 🆁 – read only.

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.

Response example

{
 "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

To add a video archive, use the following method:

POST /videos/

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

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.

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.

{
 "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:

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

CURL example

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 parameters. Example.

Response example

{
 "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.

Upload a video file

To upload a video file, use the following method:

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.

CURL example

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

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

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.

CURL example

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

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/