.. _video-about:

How to Use Video Face Detection API
---------------------------------------------------------------

.. rubric:: In this section:

.. contents::
   :local:


Endpoint
^^^^^^^^^^^^^^^^^^^

Video face detection API requests are to be sent to ``http://<findface-video-manager IP address>:18810/``. API requests are executed by the ``findface-video-manager`` component.

.. _job:

Job Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Video face detection API operates on a ``job`` object which represents a video processing task that the ``findface-video-manager`` component issues to ``findface-video-worker``. 

Each ``job`` object has the following attributes:

* ``id``: job id specified by a user.
* ``stream_url``: URL/address of video stream/file to process.
* ``labels``: tag(s) that will be used by the ``findface-facerouter`` component to find processing directives for faces detected in this stream.
* ``single_pass``: if true, disable restarting video processing upon error (by default, false).
* ``router_url``: IP address and port of the ``findface-facerouter`` component to receive detected faces from the ``findface-video-worker`` component for processing. 
* ``status``: job status. 
* ``status_msg``: additional job status info.
* ``statistic``: job progress statistics (progress duration, number of posted faces).
* ``worker_id``: id of the ``findface-video-worker`` instance executing the job.


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.

.. rubric:: Common Error Codes

+---------------------+----------------------------------------------------------------------+------------+
| Error code          | Description                                                          | HTTP code  |
+=====================+======================================================================+============+
| ``UNKNOWN_ERROR``   | Error with unknown origin.                                           | 500        | 
+---------------------+----------------------------------------------------------------------+------------+
| ``BAD_REQUEST``     | The request cannot be read, or some method parameters are invalid.   | 400        |
+---------------------+----------------------------------------------------------------------+------------+
| ``CONFLICT``        | Conflict.                                                            | 409        |
+---------------------+----------------------------------------------------------------------+------------+
| ``NOT_FOUND``       | Job not found.                                                       | 404        |
+---------------------+----------------------------------------------------------------------+------------+ 
| ``DELETING``        | The previously requested job removal is in progress.                 | 423        |
+---------------------+----------------------------------------------------------------------+------------+