How to Use Video Face Detection API

In this section:

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

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