Video Face Detection API Methods

In this section:

Create Job

POST /job/:id

This method creates a video processing task (job) for the findface-video-worker component.

Parameters in path segments

:id: job id

Parameters in request body:

  • stream_url: URL/address of a 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 video stream.
  • single_pass: if true, disable restarting video processing upon error (by default, false).
  • Other video stream parameters that differ from common video stream parameters specified in the findface-video-manager configuration file.

Returns:

A job object: all parameters from the request, as well as some read-only attributes.

Example

Request

curl -s 'http://localhost:18810/job/myid-123' --data '{"stream_url":"http://1.2.3.4/stream.mp4", "labels": {"district": "SVAO"}}' | jq

Response

{
  "id": "myid-123",
  "stream_url": "http://1.2.3.4/stream.mp4",
  "labels": {
    "district": "SVAO"
  },
  "router_url": "http://localhost:1514/",
  "single_pass": false,
  "status": "AWAITING",
  "status_msg": "",
  "statistic": {
    "processed_duration": 0,
    "faces_posted": 0
  },
  "worker_id": ""
}

List Existing Jobs

GET /jobs

This method returns the list of all existing jobs.

Parameters:

This method doesn’t accept any parameters.

Returns:

JSON representation with the list of all jobs.

Example

Request

curl -s 'http://localhost:18810/jobs' | jq

Response

[
    {
        "id": "b9c73bhg74hnekpaa0o0",
        "stream_url": "http://1.2.3.4/stream.mp4",
        "labels": {
            "district": "SVAO"
        },
        "router_url": "http://localhost:1514/",
        "single_pass": false,
        "status": "AWAITING",
        "status_msg": "",
        "worker_id": ""
    },
    {
        "id": "b9c73rhg74hnekpaa0og",
        "stream_url": "http://xxx.ru/stream.mp4",
        "labels": {
            "district": "ZAO"
        },
        "router_url": "http://localhost:1514/",
        "single_pass": false,
        "status": "AWAITING",
        "status_msg": "",
        "worker_id": ""
    }
]

Retrieve Job Parameters

GET /job/:id

This method retrieves a job parameters by id.

Parameters in path segments:

id: job id.

Returns:

JSON representation of the job object.

Example

Request

curl -s 'http://localhost:18810/job/b9c73rhg74hnekpaa0og' | jq

Response

{
    "id": "b9c73rhg74hnekpaa0og",
    "stream_url": "http://xxx.ru/stream.mp4",
    "labels": {
        "district": "ZAO"
    },
    "router_url": "http://localhost:1514/",
    "single_pass": false,
    "status": "AWAITING",
    "status_msg": "",
    "worker_id": ""
}

Delete Job

DELETE /job/:id

This method deletes a job by id.

Parameters in path segments:

id: job id.

Returns:

JSON representation of the deleted job object.

Example

Request

curl -s 'http://localhost:18810/job/myid-123' -X DELETE | jq

Response

{
  "id": "myid-123",
  "stream_url": "http://1.2.3.4/stream.mp4",
  "labels": {
    "district": "SVAO"
  },
  "router_url": "http://myrouter",
  "single_pass": false,
  "status": "DELETED",
  "status_msg": "",
  "statistic": {
    "processed_duration": 0,
    "faces_posted": 0
  },
  "worker_id": "b9kqns1g74hm6mbmhbqg"
}

Update Job

PATCH /job/:id

The method updates a job parameters by id.

Parameters in path segments:

id: job id.

Parameters in request body:

  • id: job id.
  • stream_url: URL/address of a 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 video 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.
  • New values of to-be-modified find-video-manager configuration parameters. These value have priority over those specified in the findface-video-manager configuration file.

Returns:

JSON representation of the updated job object.

Example

Request

curl -s 'http://localhost:18810/job/myid-123' -X PATCH --data '{"router_url":"http://myrouter"}' | jq
{
  "id": "myid-123",
  "stream_url": "http://1.2.3.4/stream.mp4",
  "labels": {
    "district": "SVAO"
  },
  "router_url": "http://myrouter",
  "single_pass": false,
  "status": "INPROGRESS",
  "status_msg": "",
  "statistic": {
    "processed_duration": 0,
    "faces_posted": 0
  },
  "worker_id": "b9kqns1g74hm6mbmhbqg"
}

Restart Job

RESTART /job/:id

This method restarts a job by ID.

Parameters in path segments:

id: job id.

Returns:

HTTP/1.1 200 OK on success.

Example

Request

curl -s -D - -X RESTART http://localhost:18810/job/1

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: VbhV3vC5
Date: Tue, 24 Apr 2018 15:23:19 GMT
Content-Length: 0
З