REST API reference¶

This reference contains all endpoints the IDLive Face Server provides. You can also explore the REST API via Swagger UI, it's available locally at:

http://localhost:8080/swagger-ui/index.html

api_version¶

GET /api_version

Returns the information about IDLive Face Server:

1. Version of IDLive Face.
2. Default and available pipelines.
3. Expiration date for the license.

{
  "product": "IDLive Face Server",
  "version": "1.47.0",
  "defaultPipeline": "astraea",
  "availablePipelines": ["astraea", "aphrodite"],
  "expirationDate": "2023-04-01T23:59:59Z"
}

check_liveness¶

POST /check_liveness

Performs a liveness check on an image or a series of images. Images should be send as a multipart/form-data request. In case of the series of images a single result will be produced by accumulating the results from the all images processed.

If you have configured IDLive Face Server to use multiple pipelines you can specify which one to use with the pipeline query parameter.

The endpoint always replies with 200 OK response. If the image was rejected or any other error has occurred the response will contain the error field.

{ "probability": 0.9946032, "quality": 0.72107375, "score": 5.2165456 }

{
  "error": "Interpupillary distance is too small",
  "error_code": "FACE_TOO_SMALL"
}

check_image ¶

POST /check_image

Performs an image check on a single image. Images should be sent as a multipart/form-data request, along with a JSON description specifying the pipelines and optional calibrations to be used for the checks.

Parameters

JSON structure for data parameter

{
  "domain": "GENERAL",
  "pipelines": [
    {
      "pipeline": "perseus",
      "calibration": "HARDENED"
    },
    {
      "pipeline": "dfd-1",
      "calibration": "REGULAR"
    }
  ]
}

The endpoint returns 400 Bad Request in case of malformed request data, in all other cases the endpoint returns 200 OK. If the image was rejected by one of the pipelines corresponding result will contain the error field.

{
  "serverVersion": "1.0.0",
  "licenseExpirationDate": "2025-01-01",
  "results": [
    {
      "pipeline": "perseus",
      "calibration": "HARDENED",
      "score": 0.85,
      "probability": 0.9946032,
      "quality": 0.72107375
    },
    {
      "pipeline": "dfd-pipeline",
      "calibration": "REGULAR",
      "score": 0.75,
      "probability": 0.8854023,
      "quality": 0.657824
    }
  ]
}

{
  "serverVersion": "1.0.0",
  "licenseExpirationDate": "2025-01-01",
  "results": [
    {
      "pipeline": "perseus",
      "calibration": "REGULAR",
      "error": "Failed to detect face",
      "error_code": "FACE_NOT_FOUND"
    },
    {
      "pipeline": "dfd-pipeline",
      "calibration": "REGULAR",
      "error": "Failed to detect face",
      "error_code": "FACE_NOT_FOUND"
    }
  ]
}

Example cURL Request

curl -X POST \
  http://localhost:8080/check_image \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/your/image.jpg" \
  -F 'data={"domain":"GENERAL","pipelines":[{"pipeline":"perseus","calibration":"HARDENED"},{"pipeline":"dfd-pipeline","calibration":"REGULAR"}]}'

check_liveness_batch ¶

POST /check_liveness_batch

Performs a batch of liveness checks on a series of images. Images should be send as a multipart/form-data request. Unlike the /check_liveness a response will contain results for all images.

If you have configured IDLive Face Server to use multiple pipelines you can specify which one to use with the pipeline query parameter.

The endpoint always replies with 200 OK response. For rejected images the error will be a part of a response entry specific to this image. For any other errors the response will contain the error field.

[
  {
    "file_name": "image1",
    "probability": 0.94960946,
    "quality": 0.72107375,
    "score": 2.9362469
  },
  {
    "file_name": "image2",
    "probability": 1.2596924e-5,
    "quality": 0.8110471,
    "score": -11.282045
  },
  {
    "file_name": "image3",
    "error": "Interpupillary distance is too small",
    "error_code": "FACE_TOO_SMALL"
  }
]

Note that an order of entries in the response is not guaranteed to match an order of images in the request. You need to rely on the file_name field to match the images and their results.

{
  "error": "The request contains an unsupported pipeline, rejecting",
  "error_code": null
}

bi_report ¶

GET /bi_report

Queries Business Intelligence records collected by IDLive Face Server and returns aggregated metrics about the Server's responses. You can optionally specify a required time frame.

Metrics for the quality and the probability are represented as a histogram with 0.1 interval.

{
  "theia_DESKTOP_probability_0.0-0.1": 2,
  "theia_DESKTOP_quality_0.8-0.9": 2,
  "theia_IOS_probability_0.9-1.0": 1,
  "theia_IOS_quality_0.7-0.8": 1,
  "theia_UNKNOWN_FACE_TOO_SMALL": 3,
  "theia_UNKNOWN_probability_0.0-0.1": 4,
  "theia_UNKNOWN_probability_0.9-1.0": 3,
  "theia_UNKNOWN_quality_0.7-0.8": 3,
  "theia_UNKNOWN_quality_0.8-0.9": 4,
  "total": 13
}

bi_records ¶

GET /bi_records

Returns Business Intelligence records collected by IDLive Face Server. You can optionally specify a required time frame.

System endpoints¶

health ¶

GET /health

Provides a means of checking the health of a running Server. Returns 200 if everything is ok, and 503 if there is a problem.

metrics¶

GET /metrics

The metrics in the Prometheus format. You can use them to monitor a license expiration date.