LUNA Backport 3 API (v.0.3.0)

Download OpenAPI specification:Download

VisionLabs Backport 3 API. The API version is 4.

OpenAPI specification is the only valid document providing up-to-date information about the service API.

The specification can be used:

  • By documentation generation tools to visualize the API.
  • By code generation tools.

All the documents and code generated using this specification can include inaccuracies and should be carefully checked.

OpenAPI specification can be received using the "/docs/spec" resource. The "Accept" header should be set to "application/x-yaml".

Authentication

BasicAuth

This API supports Basic Authentication for access to the account.

Header example: Authorization: Basic bG9naW46cGFzc3dvcmQ=

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Token

This API supports X-Auth-Token for access to the account.

Header example: X-Auth-Token: 11c59254-e83f-41a3-b0eb-28fae998f271

Security Scheme Type HTTP
HTTP Authorization Scheme token

accounts

create account

Create a new account with given credentials.

Automatically creates one API token for client authorization. The token is returned within the reply body.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
organization_name
required
string (organization_name) <= 128 characters

organization name

email
required
string <email> (email) <= 64 characters

email address

password
required
string (password) [ 8 .. 32 ] characters

account password

Responses

Request samples

Content type
application/json
{
  • "organization_name": "Horns and hooves",
  • "email": "hornsandhooves@ya.ru",
  • "password": "strong_password"
}

Response samples

Content type
application/json
{
  • "token": "b668c4a5-2191-476e-a261-3b4f9ce2e25e"
}

accounts options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get account info

Get current account registration information and it's status.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "organization_name": "Horns and hooves",
  • "email": "hornsandhooves@ya.ru",
  • "suspended": true
}

account options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

tokens

get account tokens

Get all authorization tokens owned by current account. This query is pageable.

Authorizations:
query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ],
  • "count": 0
}

create account token

Create an authorization token for current account.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
token_data
required
string (token_data) <= 128 characters

User data about token. Arbitrary string.

Responses

Request samples

Content type
application/json
{
  • "token_data": "For south camera"
}

Response samples

Content type
application/json
{
  • "token": "b668c4a5-2191-476e-a261-3b4f9ce2e25e"
}

delete account tokens

Delete one or several authorization tokens from current account.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
tokens
required
Array of strings <uuid4> (token)

Responses

Request samples

Content type
application/json
{
  • "tokens": [
    ]
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "Failed to validate input json. Path: 'tokens[1]', message: 'tokens[1] must match pattern [a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}'"
}

account tokens options

get options for the resource

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get account token

Get information about this token.

Authorizations:
path Parameters
token_id
required
string <uuid4> (token) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

Token unique id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "token_data": "For south camera"
}

patch account token

Change token data associated with this token.

Authorizations:
path Parameters
token_id
required
string <uuid4> (token) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

Token unique id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
token_data
required
string (token_data) <= 128 characters

User data about token. Arbitrary string.

Responses

Request samples

Content type
application/json
{
  • "token_data": "For south camera"
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "Failed to validate input json. Path: 'token_data', message: 'token_data must be string'"
}

delete account token

Delete this token.

Authorizations:
path Parameters
token_id
required
string <uuid4> (token) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

Token unique id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11002,
  • "detail": "Account corresponding login/password not found"
}

account token options

get options for the resource

Authorizations:
path Parameters
token_id
required
string <uuid4> (token) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

Token unique id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

descriptors

create descriptors

Extract descriptor(s) from an image

In order to extract any descriptors, the function performs face detection first. In case of multiple detected faces, the function will produce several descriptors (one per face). Please note that some faces may not be detected for technical challenges, e.g. very large face angles (head pose) or large occlusion. Frontal and near-frontal faces have the best results.

This function outputs detected faces positions as bounding rectangles. Each rectangle is defined by it's top-left corner position, width and height. Note, that coordinate system origin is at the top-left corner of the image. The face rectangles are stored in rect objects per face. Aside from face detector response, the function also outputs bounding rectangles scaled and biased to resemble conformance to ISO IEC 19794-5 2005(E). To 'resemble conformance' here means that the standard dictates not only the bounding rectangle shape but also photoshooting conditions. Since Luna is a general system and not a true biometric one, it has no means to guarantee the conditions. However, it can detect person's eyes on a picture and build a rectangle with proportions described in the standard. The best results are observed on non-rotated faces while pose variations introduce errors. Note, that the procedure of ISO rectangle construction does not take image boundaries into account. The resulting rectangle may outstep the image boundaries. The client is responsible to do proper padding if image cropping is desired. The ISO face rectangles are stored in rectISO objects per face.

Face detection step for arbitrary image is mandatory, and for warped image it will be skipped (see descripton for warped_image in the query parameters section below). All the remaining steps can be enabled or disabled. E.g. while descriptor extraction is enabled by default, the client may disable it provided only face bounding boxes are required. See additional feature descriptions in the query parameters section below. In order to make face descriptor invariant to some pose variations and scale, each face detection area is cropped from the source image. Then several affine transformations are applied to the crop including rotation and scaling. This process is called warping. Since warping scales all cropped images to the same size, one won't get a much better face descriptor from a higher resolution photograph. In other way around, while it is possible to extract descriptors from smaller images, matching quality of such descriptors will be lower due to the lack of detail. To give an idea, reasonable face bounding box size is about 150x150 pixels. It is possible to estimate additional per face attributes, including:

  • overall face image quality (suitablity for recognition);
  • age;
  • gender;
  • ethnicities;
  • emotions;
  • head pose;

These attributes are not stored in the DB.

Upload an existing descriptor

To upload an existing descriptor you should set content-type header to application/x-vl-face-descriptor for raw descriptor and application/x-vl-xpk for xpk-file. In this case request query parameterss will be ignored. Note, that external descriptors should be extracted with the same descriptor model version as used in the Luna installation. Otherwise, you won't be able to match them.

WARNING Default descriptor version to extract from image is default descriptor version configured in the system (one of 52, 54, 56, 57, 58). The older descriptor versions are no longer supported.

Authorizations:
query Parameters
estimate_attributes
integer
Default: 0
Enum: 0 1

Whether to estimate basic face attributes (age, gender) from the image.

Attributes are typically floating point probabilities in [0..1] range. The attributes are stored in attributes object per face.

estimate_emotions
integer
Default: 0
Enum: 0 1

Whether to estimate emotions from the image.

estimate_ethnicities
integer
Default: 0
Enum: 0 1

Whether to estimate ethnicities from the image.

estimate_quality
integer
Default: 0
Enum: 0 1

Whether to estimate image quality from the image.

The estimated quality values is a floating point probability in [0..1] range. The quality is stored in quality parameter per face.

score_threshold
number <double> [ 0 .. 1 ]
Default: 0
Example: score_threshold=0.95

Descriptor quality score threshold. All the face descriptors with quality score below the threshold will be ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors (if left).

warped_image
integer
Default: 0
Enum: 0 1

Whether input image is a warped or arbitrary image. Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.

The warped image has the following properties:

it's size is always 250x250 pixels it's always in RGB color format it always contains just a single face the face is always centered and rotated so that imaginary line between the eyes is horizontal.

extract_descriptor
integer
Default: 1
Enum: 0 1

Whether to extract face descriptor(s).

Useful when face descriptor is not actually required and only face detection bounding rectangle (with optional attributes and quality estimation) is enough. Note, that in this case face structure will lack the id member.

estimate_head_pose
integer
Default: 0
Enum: 0 1

Whether to estimate head pose from the image.

Ignored with warped images (see warped_image parameter).

pitch__lt
number [ 0 .. 180 ]
Example: pitch__lt=10

Pitch threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

yaw__lt
number [ 0 .. 180 ]
Example: yaw__lt=10

Yaw threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

roll__lt
number [ 0 .. 180 ]
Example: roll__lt=10

Roll threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

extract_exif
integer
Default: 0
Enum: 0 1

Whether to extract EXIF meta information from input JPEG images.

Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.

This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification specification for details.

no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
required
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/gif" "image/x-windows-bmp" "image/x-portable-pixmap" "application/x-vl-face-descriptor" "application/x-vl-xpk" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-gif-base64" "image/x-windows-bmp-base64" "image/x-portable-pixmap-base64" "application/x-vl-face-descriptor-base64" "application/x-vl-xpk-base64"

An indicator of the media type of the request body.

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "faces": [
    ],
  • "exif": {
    }
}

get descriptors

Get info of all descriptors owned by current account.

Authorizations:
query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "descriptors": [
    ],
  • "count": 1
}

descriptors options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get descriptor

Get descriptor info.

Authorizations:
path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "last_update": "2018-08-11T09:11:41.674Z",
  • "person_id": "string",
  • "lists": [
    ]
}

descriptor options

get options for the resource

path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

lists

get descriptor lists

Get all lists that this descriptor is attached to.

Authorizations:
path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

patch descriptor lists

Attach or detach a descriptor to the list.

Once detached, descriptor's TTL is reset to the default value. If not attached to a person or to a list, this descriptor will be eventually garbage-collected.

Authorizations:
path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

query Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

do
required
string (do)
Enum: "attach" "detach"

action - attach or detach an object to/from a list

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12014,
  • "detail": "Required parameters 'list_id' not found"
}

descriptor lists options

get options for the resource

Authorizations:
path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get person lists

Get all lists that this person is attached to.

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

patch person lists

Attach or detach a person to the list.

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

query Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

do
required
string (do)
Enum: "attach" "detach"

action - attach or detach an object to/from a list

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12014,
  • "detail": "Required parameters 'list_id' not found"
}

person lists options

get options for the resource

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get lists

Get ids of all lists owned by current account. This query is pageable.

Authorizations:
query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "lists": {
    },
  • "persons_list_count": 0,
  • "descriptors_list_count": 0
}

create list

Create a list.

Authorizations:
query Parameters
type
string
Default: "persons"
Enum: "persons" "descriptors"

List data type - persons or descriptors.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
list_data
string (user_data) <= 128 characters

User-defined data. Arbitrary string.

Responses

Request samples

Content type
application/json
{
  • "list_data": "info"
}

Response samples

Content type
application/json
{
  • "list_id": "string"
}

delete lists

Delete one or multiple lists.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
lists
required
Array of strings <uuid4> (list_id)

Array of lists to delete.

Responses

Request samples

Content type
application/json
{
  • "lists": [
    ]
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "Failed to validate input json. Path: 'lists', message: 'lists must be array'"
}

lists options

get options for the resource

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get list

Get a list. This query is pageable.

Authorizations:
path Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
Example
{
  • "persons": [
    ],
  • "list_data": "info",
  • "count": 1
}

patch a list

Patch list data associated with this list.

Authorizations:
path Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
list_data
required
string (user_data) <= 128 characters

User-defined data. Arbitrary string.

Responses

Request samples

Content type
application/json
{
  • "list_data": "info"
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "Failed to validate input json. Path: 'list_data', message: 'token_data must be string'"
}

delete list

Delete a list.

Authorizations:
path Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11002,
  • "detail": "Account corresponding login/password not found"
}

list options

get options for the resource

Authorizations:
path Parameters
list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

List id.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11002,
  • "detail": "Account corresponding login/password not found"
}

linker

Attach or detach several descriptors or persons to list.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema: application/json
One of
action
required
string (do)
Enum: "attach" "detach"

action to perform - attach or detach

descriptor_ids
required
Array of strings <uuid4> (uuid4)

Descriptor ids to operate with.

list_id
required
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...

List id. uuid4

Responses

Request samples

Content type
application/json
Example
{
  • "action": "attach",
  • "descriptor_ids": [
    ],
  • "list_id": "string"
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "Failed to validate input json. Path: 'list_id', message: 'list_id must be string'"
}

linker options

get options for the resource

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

portrait

get portrait

Get descriptor origin portrait.

Authorizations:
path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
image/jpeg
<binary image>

portrait options

get options for the resource

path Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get portrait thumbnails

get descriptor portrait thumbnail

Authorizations:
path Parameters
descriptor_id_with_thumbnails
required
string^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Face descriptor unique identifier with thumbnail version specified. Thumbnails are reduced-size versions of portraits. Each thumbnail corresponds to a number equal to the side with maximum length. The following thumbnail versions are only supported: _32, _64, _96, _160.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
image/jpeg
<binary image>

portrait thumbnails options

get options for the resource

path Parameters
descriptor_id_with_thumbnails
required
string^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Face descriptor unique identifier with thumbnail version specified. Thumbnails are reduced-size versions of portraits. Each thumbnail corresponds to a number equal to the side with maximum length. The following thumbnail versions are only supported: _32, _64, _96, _160.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

persons

create person

Create person

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
user_data
string (user_data) <= 128 characters

User-defined data. Arbitrary string.

external_id
string (person_external_id) <= 36 characters

External id of the person, if it has its own mapping in external system.

Responses

Request samples

Content type
application/json
{
  • "user_data": "info",
  • "external_id": "14159261415926"
}

Response samples

Content type
application/json
{
  • "person_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515"
}

get persons

Get persons by filters.

Authorizations:
query Parameters
user_data
string (user_data) <= 128 characters
Example: user_data=info

find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.

external_id
string (person_external_id) <= 36 characters
Example: external_id=14159261415926

External ID. When filtering by an external ID, you must specify the full external_id value.

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "persons": [
    ],
  • "count": 1
}

persons options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get person

Get person

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "user_data": "info",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "external_id": "14159261415926",
  • "descriptors": [
    ],
  • "lists": [
    ]
}

patch person

Patch person. Required user data or external id in body

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema: application/json
user_data
string (user_data) <= 128 characters

User-defined data. Arbitrary string.

external_id
string (person_external_id) <= 36 characters

External id of the person, if it has its own mapping in external system.

Responses

Request samples

Content type
application/json
{
  • "user_data": "info",
  • "external_id": "14159261415926"
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "detail": "user_data must be shorter than or equal to 128 characters"
}

delete person

Delete person

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11002,
  • "detail": "Account corresponding login/password not found"
}

person options

get options for the resource

path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get person descriptors

Get person descriptors

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "descriptors": [
    ]
}

patch person descriptors

Attach or detach a descriptor to the person.

Authorizations:
path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

query Parameters
descriptor_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: descriptor_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

Face descriptor unique identifier.

do
required
string (do)
Enum: "attach" "detach"

action - attach or detach descriptor to/from person

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 11018,
  • "detail": "Descriptor with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found."
}

person descriptors options

get options for the resource

path Parameters
person_id
required
string <uuid4> (uuid4) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

person id (person_id received in the "create person" request)

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

matching

verification

Verification is done via matching a reference descriptor with a set of candidate descriptors belonging to a single person.

The reference descriptor should be specified explicitly. The set of candidate descriptors consists of all descriptors attached to the verified person.

Authorizations:
query Parameters
descriptor_id
required
string <uuid4> (descriptor_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: descriptor_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

descriptor id for verification

person_id
required
string <uuid4> (person_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: person_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

person id for verification

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "candidates": [
    ]
}

verify options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

identification

Identification is done via matching a reference descriptor with a list of candidate persons' descriptors.

The reference descriptor may be specified explicitly or taken from a person defined by the person ID.

The matching process produces similarities for each candidate. Maximum of top 5 most similar results are then selected. Identification result is a short list of the most similar persons and their similarity scores. It's up to the user to decide whether the similarity score is high enough to consider it a successful match or not.

Person ID or a descriptor ID can be set as a reference for matching. An ID of persons list or the set of persons IDs can be specified as candidates for matching.

Only one of descriptor_id or person_id query parameters should be specified as the reference at a time. You can not set both at once.

Only one of list_id or persons_ids should be specified as the candidate.

If you specify several parameters, the service will choose only one of them.

Authorizations:
query Parameters
person_id
string <uuid4> (person_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: person_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

reference person id

descriptor_id
string <uuid4> (descriptor_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: descriptor_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

reference descriptor id

list_id
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

Candidates list id

person_ids
string <list of uuid>

Comma-separated list of candidate person ids

limit
integer (match_limit) [ 1 .. 5 ]
Default: 3

maximum of number candidates in a matching response

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "candidates": [
    ]
}

identify options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

raw match

Matching person or descriptor by descriptors. Descriptors can be represent as a ID of descriptors list or a descriptor ID set.

Only one of descriptor_id or person_id query parameters should be specified as the reference at a time. You can not set both at once. Also only one of list_id or descriptor_ids should be specified as the candidate. If you specify several parameters service will choose one of them.

Authorizations:
query Parameters
person_id
string <uuid4> (person_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: person_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

reference person id

descriptor_id
string <uuid4> (descriptor_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: descriptor_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

reference descriptor id

list_id
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

Candidates list id

descriptor_ids
string <list of uuid>

Comma-separated list of candidate descriptor ids

limit
integer (match_limit) [ 1 .. 5 ]
Default: 3

maximum of number candidates in a matching response

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "candidates": [
    ]
}

match options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

search

Search a person by photo. This request is just a simple way to tell "extract a descriptor then match it with a list ". This request is equivalent to POST'ing to /descriptors then to /matching/identify or /matching/match.

Search request requires the input photo to contain only one face.

Only one of list_id or descriptor_ids, person_ids query parameters should be specified as the candidate at a time. If you specify several parameters service will choose one of them.

Authorizations:
query Parameters
list_id
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

Candidates list id

descriptor_ids
string <list of uuid>

Comma-separated list of candidate descriptor ids

person_ids
string <list of uuid>

Comma-separated list of candidate person ids

estimate_attributes
integer
Default: 0
Enum: 0 1

Whether to estimate basic face attributes (age, gender) from the image.

Attributes are typically floating point probabilities in [0..1] range. The attributes are stored in attributes object per face.

estimate_emotions
integer
Default: 0
Enum: 0 1

Whether to estimate emotions from the image.

estimate_ethnicities
integer
Default: 0
Enum: 0 1

Whether to estimate ethnicities from the image.

estimate_quality
integer
Default: 0
Enum: 0 1

Whether to estimate image quality from the image.

The estimated quality values is a floating point probability in [0..1] range. The quality is stored in quality parameter per face.

score_threshold
number <double> [ 0 .. 1 ]
Default: 0
Example: score_threshold=0.95

Descriptor quality score threshold. All the face descriptors with quality score below the threshold will be ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors (if left).

warped_image
integer
Default: 0
Enum: 0 1

Whether input image is a warped or arbitrary image. Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.

The warped image has the following properties:

it's size is always 250x250 pixels it's always in RGB color format it always contains just a single face the face is always centered and rotated so that imaginary line between the eyes is horizontal.

estimate_head_pose
integer
Default: 0
Enum: 0 1

Whether to estimate head pose from the image.

Ignored with warped images (see warped_image parameter).

pitch__lt
number [ 0 .. 180 ]
Example: pitch__lt=10

Pitch threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

yaw__lt
number [ 0 .. 180 ]
Example: yaw__lt=10

Yaw threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

roll__lt
number [ 0 .. 180 ]
Example: roll__lt=10

Roll threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted. Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.

extract_exif
integer
Default: 0
Enum: 0 1

Whether to extract EXIF meta information from input JPEG images.

Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.

This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification specification for details.

limit
integer (match_limit) [ 1 .. 5 ]
Default: 3

maximum of number candidates in a matching response

no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
required
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/gif" "image/x-windows-bmp" "image/x-portable-pixmap" "application/x-vl-face-descriptor" "application/x-vl-xpk" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-gif-base64" "image/x-windows-bmp-base64" "image/x-portable-pixmap-base64" "application/x-vl-face-descriptor-base64" "application/x-vl-xpk-base64"

An indicator of the media type of the request body.

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
Example
{
  • "face": {
    },
  • "candidates": [
    ]
}

search options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

liveness

predict liveness

Predict liveness probability in input images.

The response contains the probability that there is a real person in the image, and it is not a presentation attack.

Liveness V1 or Liveness V2 can be used for this resource. Liveness V2 does not use "meta" section of the request.

The incoming images should correspond the requirements of the utilized Liveness. See "Administrator’s manual" for details.

Liveness estimation is not supported for samples (warped images).

Authorizations:
query Parameters
aggregate
integer
Default: 0
Enum: 1 0
Example: aggregate=1

whether to aggregate liveness estimations.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/x-portable-pixmap" "image/tiff" "multipart/form-data" "application/json" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-portable-pixmap-base64"
Request Body schema:
object (LivenessMeta)

Device information. This information can significantly decrease the overall error rate.

The "meta" object is not mandatory. If you are not sure about any of the parameters, set "UNKNOWN" value or don't pass meta.

The specified meta is applied to all the images within the request.

x_meta
object

The JSON string with any additional information

required
Array of image_binary_for_multipart (string) or image_base64_for_multipart (string) (image_list_for_multipart) non-empty

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "images": [
    ],
  • "aggregate_estimations": {
    }
}

handlers

face extractor

Extract a descriptor from an image or save input descrptor, create person with this descriptor, attach person to a predefined list.

If the image contains several faces, the best one (in terms of score) will be used.

Input images can be filtered according to predefined thresholds (quality threshold and head angles).

The resulting fields of the created face object differ depending on the handler configuration.

Authorizations:
query Parameters
user_data
string (user_data) <= 128 characters
Example: user_data=info

User-defined data. Arbitrary string.

external_id
string (person_external_id) <= 36 characters
Example: external_id=14159261415926

External id of the person.

warped_image
integer
Default: 0
Enum: 0 1

Whether input image is a warped or arbitrary image. Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.

The warped image has the following properties:

it's size is always 250x250 pixels it's always in RGB color format it always contains just a single face the face is always centered and rotated so that imaginary line between the eyes is horizontal.

no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
required
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/gif" "image/x-windows-bmp" "image/x-portable-pixmap" "application/x-vl-face-descriptor" "application/x-vl-xpk" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-gif-base64" "image/x-windows-bmp-base64" "image/x-portable-pixmap-base64" "application/x-vl-face-descriptor-base64" "application/x-vl-xpk-base64"

An indicator of the media type of the request body.

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "person_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "face": {
    },
  • "exif": {
    }
}

get extractor handler

The request enables you to get the parameters specified for the extractor handler.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "handler_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "last_update_time": "2018-08-11T09:11:41.674Z",
  • "policies": {
    },
  • "type": "extractor",
  • "version": 1
}

patch extractor handler

The request enables you to update the extractor handler parameters. You should specify at least one parameters in the request.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema: application/json
list_id
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...

List id. uuid4

estimate_attributes
integer (estimate_attributes)
Default: 0
Enum: 0 1

whether to estimate basic attributes on the image.

estimate_emotions
integer (estimate_emotions)
Default: 0
Enum: 0 1

whether to estimate emotions on the image.

estimate_ethnicities
integer (estimate_ethnicities)
Default: 0
Enum: 0 1

whether to estimate ethnicities on the image.

estimate_quality
integer (estimate_quality)
Default: 0
Enum: 0 1

whether to estimate input face image quality.

estimate_head_pose
integer (estimate_head_pose)
Default: 0
Enum: 0 1

whether to estimate head pose on the image.

extract_exif
integer (extract_exif)
Default: 0
Enum: 0 1

whether to extract EXIF meta information from input JPEG images.

Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.

This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification for details.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]

maximum deviation yaw angle from 0.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]

maximum deviation roll angle from 0.

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]

maximum deviation pitch angle from 0.

score_threshold
number (score_threshold) [ 0 .. 1 ]

descriptor quality score threshold. All the attributes with quality score below the threshold will be ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors (if left).

Responses

Request samples

Content type
application/json
{
  • "list_id": "string",
  • "estimate_attributes": 0,
  • "estimate_emotions": 0,
  • "estimate_ethnicities": 0,
  • "estimate_quality": 0,
  • "estimate_head_pose": 0,
  • "extract_exif": 0,
  • "yaw_threshold": 55,
  • "roll_threshold": 45,
  • "pitch_threshold": 35,
  • "score_threshold": 0.9
}

Response samples

Content type
application/json
{
  • "version": 1
}

extractor options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

verify face

Extract a descriptor from an image or save input descrptor, then match it to a person.

If the image contains several faces, the best one (in terms of score) will be used.

The resulting fields of the created face object differ depending on the handler configuration.

Authorizations:
query Parameters
warped_image
integer
Default: 0
Enum: 0 1

Whether input image is a warped or arbitrary image. Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.

The warped image has the following properties:

it's size is always 250x250 pixels it's always in RGB color format it always contains just a single face the face is always centered and rotated so that imaginary line between the eyes is horizontal.

person_id
required
string <uuid4> (person_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...
Example: person_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

person ID

no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
required
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/gif" "image/x-windows-bmp" "image/x-portable-pixmap" "application/x-vl-face-descriptor" "application/x-vl-xpk" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-gif-base64" "image/x-windows-bmp-base64" "image/x-portable-pixmap-base64" "application/x-vl-face-descriptor-base64" "application/x-vl-xpk-base64"

An indicator of the media type of the request body.

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "candidates": [
    ],
  • "face": {
    },
  • "exif": {
    }
}

get verify handler

The request enables you to get the parameters specified for the verify handler.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "handler_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "last_update_time": "2018-08-11T09:11:41.674Z",
  • "policies": {
    },
  • "type": "verify",
  • "version": 1
}

patch verify handler

The request enables you to update the verify handler parameters. You should specify at least one parameters in the request.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema: application/json
estimate_attributes
integer (estimate_attributes)
Default: 0
Enum: 0 1

whether to estimate basic attributes on the image.

estimate_emotions
integer (estimate_emotions)
Default: 0
Enum: 0 1

whether to estimate emotions on the image.

estimate_ethnicities
integer (estimate_ethnicities)
Default: 0
Enum: 0 1

whether to estimate ethnicities on the image.

estimate_quality
integer (estimate_quality)
Default: 0
Enum: 0 1

whether to estimate input face image quality.

estimate_head_pose
integer (estimate_head_pose)
Default: 0
Enum: 0 1

whether to estimate head pose on the image.

extract_exif
integer (extract_exif)
Default: 0
Enum: 0 1

whether to extract EXIF meta information from input JPEG images.

Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.

This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification for details.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]

maximum deviation yaw angle from 0.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]

maximum deviation roll angle from 0.

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]

maximum deviation pitch angle from 0.

score_threshold
number (score_threshold) [ 0 .. 1 ]

descriptor quality score threshold. All the attributes with quality score below the threshold will be ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors (if left).

verify_threshold
number (verify_threshold) [ 0 .. 1 ]

Verify threshold. Face with matching score under threshold will be ignored (negative status of verification), but still exists in list of candidates.

Responses

Request samples

Content type
application/json
{
  • "estimate_attributes": 0,
  • "estimate_emotions": 0,
  • "estimate_ethnicities": 0,
  • "estimate_quality": 0,
  • "estimate_head_pose": 0,
  • "extract_exif": 0,
  • "yaw_threshold": 55,
  • "roll_threshold": 45,
  • "pitch_threshold": 35,
  • "score_threshold": 0.9,
  • "verify_threshold": 0.9
}

Response samples

Content type
application/json
{
  • "version": 1
}

verify options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

batch verification

Raw API allows to do similarity and verification status calculations for input descriptors.

Authorizations:
query Parameters
no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Content-Type
string
Enum: "application/json" "application/msgpack"

Format of a request body data

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema:
required
Array of xpk_file_entity (object) or sdk_descriptor_entity (object) or raw_descriptor_entity (object) non-empty

reference list for verification

required
Array of xpk_file_entity (object) or sdk_descriptor_entity (object) or raw_descriptor_entity (object) non-empty

candidates for verification

Responses

Request samples

Content type
{
  • "references": [
    ],
  • "candidates": [
    ]
}

Response samples

Content type
application/json
{
  • "matches": [
    ]
}

raw batch verification options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

identify face

Extract a descriptor from an image or save input descrptor, then match it to a predefined list of candidates.

If the image contains several faces, the best one (in terms of score) will be used.

The resulting fields of the created face object differ depending on the handler configuration.

Authorizations:
query Parameters
warped_image
integer
Default: 0
Enum: 0 1

Whether input image is a warped or arbitrary image. Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.

The warped image has the following properties:

it's size is always 250x250 pixels it's always in RGB color format it always contains just a single face the face is always centered and rotated so that imaginary line between the eyes is horizontal.

no_cache
integer (int01)
Default: 0
Enum: 0 1

Whether to force database query for fetching data for handler.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Content-Type
required
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/gif" "image/x-windows-bmp" "image/x-portable-pixmap" "application/x-vl-face-descriptor" "application/x-vl-xpk" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-gif-base64" "image/x-windows-bmp-base64" "image/x-portable-pixmap-base64" "application/x-vl-face-descriptor-base64" "application/x-vl-xpk-base64"

An indicator of the media type of the request body.

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "candidates": [
    ],
  • "face": {
    },
  • "exif": {
    }
}

get identify handler

The request enables you to get the parameters specified for the identify handler.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "handler_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "last_update_time": "2018-08-11T09:11:41.674Z",
  • "policies": {
    },
  • "type": "identify",
  • "version": 1
}

patch identify handler

The request enables you to update the identify handler parameters. You should specify at least one parameters in the request.

Authorizations:
header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Request Body schema: application/json
list_id
string <uuid4> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][...

List id. uuid4

limit
integer (handler_matching_limit) [ 1 .. 5 ]
Default: 3

matching limit

estimate_attributes
integer (estimate_attributes)
Default: 0
Enum: 0 1

whether to estimate basic attributes on the image.

estimate_emotions
integer (estimate_emotions)
Default: 0
Enum: 0 1

whether to estimate emotions on the image.

estimate_ethnicities
integer (estimate_ethnicities)
Default: 0
Enum: 0 1

whether to estimate ethnicities on the image.

estimate_quality
integer (estimate_quality)
Default: 0
Enum: 0 1

whether to estimate input face image quality.

estimate_head_pose
integer (estimate_head_pose)
Default: 0
Enum: 0 1

whether to estimate head pose on the image.

extract_exif
integer (extract_exif)
Default: 0
Enum: 0 1

whether to extract EXIF meta information from input JPEG images.

Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.

This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification for details.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]

maximum deviation yaw angle from 0.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]

maximum deviation roll angle from 0.

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]

maximum deviation pitch angle from 0.

score_threshold
number (score_threshold) [ 0 .. 1 ]

descriptor quality score threshold. All the attributes with quality score below the threshold will be ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors (if left).

identify_threshold
number (identify_threshold) [ 0 .. 1 ]

Identify threshold. Face with matching score under threshold will be ignored.

Responses

Request samples

Content type
application/json
{
  • "list_id": "string",
  • "limit": 3,
  • "estimate_attributes": 0,
  • "estimate_emotions": 0,
  • "estimate_ethnicities": 0,
  • "estimate_quality": 0,
  • "estimate_head_pose": 0,
  • "extract_exif": 0,
  • "yaw_threshold": 55,
  • "roll_threshold": 45,
  • "pitch_threshold": 35,
  • "score_threshold": 0.9,
  • "identify_threshold": 0.9
}

Response samples

Content type
application/json
{
  • "version": 1
}

identify options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

documents

get openapi documentation

Get service OpenApi documentation. If Accept request header is of type application/x-yaml, returns documentation in yaml format or returns html documentation, if Accept-Type is text/html

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Accept
string (accept_docs_handler)
Enum: "application/x-yaml" "text/html"

acceptable type of recieving data

Responses

Response samples

Content type
application/json
{
  • "error_code": 12024,
  • "detail": "Bad/incomplete input data",
  • "desc": "Unsupported media type"
}

get development manual

Get sphinx documentation - Development Manual. After the request you will be redirected to the page /docs/dev/index.html

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

config

get service configuration

Get service configuration. Passwords and tokens will be hidden in the response.

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Accept
string
Enum: "application/json" "text/plain"

acceptable type of receiving data

Responses

Response samples

Content type
{
  • "INFLUX_MONITORING": {
    }
}

health

get health

get health of service

query Parameters
include_luna_services
integer
Default: 0
Enum: 0 1

whether to perform healthchecks for dependent luna services.

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "execution_time": 0.123
}

health options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}

get health (redirect)

get health of service (redirect)

query Parameters
include_luna_services
integer
Default: 0
Enum: 0 1

whether to perform healthchecks for dependent luna services.

header Parameters
Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "execution_time": 0.123
}

version

get version

get versions of services

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "Version": {
    }
}

version options

get options for the resource

header Parameters
Origin
string
Example: http://example.com

The Origin header indicates the origin of the cross-site access request

Luna-Request-Id
string <timestamp,uuid4> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error"
}