How to Use Video Object Detection API

In this section:

Job Life Cycle

videomanager-statuses_en

  • AWAITING – the job is waiting for a suitable instance of the video-worker. The job gets this status immediately after the creation, or after stopping with an error if single_pass==false and it can be restarted. A job can be in this status while it has not yet been assigned, when there are no instances of the video-worker with suitable labels, or when the maximum number of video streams that video-worker allowed to process exceeds the capacity value.

  • STARTING – the job has been sent to the video-worked, but hasn’t processed any frame yet.

  • INPROGRESS – the job is being processed by the video-worker and has processed at least one frame.

  • COMPLETED – the job was completed successfully at the end of the file or stream. Only jobs with single_pass==true are permitted to remain in this status for a long time, other ones will be restarted.

  • INTERRUPTED – the stream processing was interrupted with an error. If the job hasn’t single_pass option, it will be restarted.

  • MISCONFIGURED – the assigned video-worker can’t process this job due to configuration inaccuracy. The job will try to run on another video-worker.

  • TOO_MANY_CAMERAS – the stream is unable to be started due to license restrictions. The job can try to run again, if there will be free slots in the license.

  • NOT_STARTED – the attempt to process is completed by an error without processing any frame. The job can try to run on another video-worker.

  • DISCONNECTED – the connection with the assigned to process the job video-worker has been lost.

  • DISABLED – the job is set to enabled: false. This status is accessible from any status. After changing option enabled to true, the job will switch to AWAITING.

Endpoint

Video object detection API requests are to be sent to http://<video-manager_IP_address>:18810/. API requests are executed by the video-manager component.

Job

Video object detection API operates on a job object which represents a video processing task (ie, job) that the video-manager component issues to video-worker.

Each job object has the following attributes:

  • id: job id.

  • enabled: active status.

  • stream_url: URL/address of video stream/file to process.

  • labels: key-value labels, that will be used by the router component (for example facerouter) to find processing directives for objects detected in this stream.

  • router_url: URL/address of the router component (for example, facerouter) to receive detected objects from the video-worker component for processing.

  • router_events_url: URL/address of the router component (for example, facerouter), that uses events extraction.

  • single_pass: if true, disable restarting video processing upon error (by default, false).

  • stream_settings: video stream settings that duplicate those in the video-manager.yaml configuration file (while having priority over them).

  • stream_settings_gpu: deprecated video stream settings. Not recommended for use. Only for compatibility.

  • status: job status.

  • status_msg: additional job status info.

  • statistic: job progress statistics (progress duration, number of posted and not posted objects, processing fps, the number of processed and dropped frames, job start time, etc.).

  • restream_url: websocket URL where processing stream with detected objects streams live time.

  • restream_direct_url: websocket URL where original stream with input quality streams live time.

  • shots_url: HTTP URL where actual stream screenshot can be downloaded.

  • worker_id: unique id of the video worker instance with a processing job.

  • version: job version.

Error Reporting

If a method fails, it always returns a response with a HTTP code other than 200, and a JSON body containing the error description. The error body always includes at least two fields: code and desc.

  • code is a short string in CAPS_AND_UNDERSCORES, usable for automatic decoding.

  • desc is a human-readable description of the error and should not be interpreted automatically.

Common Error Codes

Error code

Description

HTTP code

UNKNOWN_ERROR

Error with unknown origin.

500

BAD_PARAM

The request can be read, however, some method parameters are invalid. This response type contains additional attributes param and value to indicate which parameters are invalid.

400

MALFORMED_REQUEST

The request is malformed and cannot be read.

400

SOURCE_NOT_FOUND

Detection not found in cache.

400

CONFLICT

Conflict.

409

NOT_FOUND

Job not found.

404

EXTRACTION_ERROR | STORAGE_ERROR | LICENSE_ERROR | CACHE_ERROR

Service Unavailable.

523