LUNA PLATFORM 5 API (v.5.14.0)

Download OpenAPI specification:Download

VisionLabs Luna Platform 5 API. The API version is 6.

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

version

get version

get versions of services

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

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

Responses

Response samples

Content type
application/json
{
  • "LUNA PLATFORM": {
    },
  • "luna-api": {
    },
  • "luna-events": {
    },
  • "luna-faces": {
    },
  • "luna-image-store-bodies-samples": {
    },
  • "luna-image-store-faces-samples": {
    },
  • "luna-image-store-images": {
    },
  • "luna-handlers": {
    },
  • "luna-tasks": {
    },
  • "luna-matcher-proxy": {
    }
}

version options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

sdk

sdk resource

Detect faces and/or human bodies and estimate attributes on the input images. After the request is performed, the received data is not saved to the database or Image Store, it is only returned in the response.

The order of input images corresponds to the order of the elements in the output JSON.

If an input image is corrupted, an error is returned for the image. The processing of the other images continues in normal mode.

query Parameters
image_type
integer
Default: 0
Enum: 0 1 2

type of input image. 0 - raw image, 1 - face warped image, 2 - body warped image

multiface_policy
integer (multiface_policy)
Default: 1
Enum: 0 1 2

multiple face detection policy:

  • 0 - do not process images with several detected faces.

    If detect_body is enabled, the system will attempt to detect a human body related to the detected face. If a human body is detected, its detection will be associated with the same event as the face.

    If there is no face detected in the image, no human body detections will be returned. Thus there will be no human body detection returned if detect_face is disabled.

  • 1 - process images with several detected faces and/or human bodies.

    If detect_body is enabled, all the detections of human bodies will be returned. Face detection and human body detection of the same person will be associated with the same event.

    The detections of human bodies are returned even if there were no faces found.

  • 2 - get the best face detection from the image. A single face of the best quality is detected in the image.

    If detect_body is enabled, the system will attempt to detect a human body related to the detected face. If a human body is detected, its detection will be associated with the same event as the face.

    If there is no face detected in the image, no human body detections will be returned. Thus there will be no human body detection returned if detect_face is disabled.

detect_face
integer
Default: 0
Enum: 0 1

whether to detect faces on the image.

detect_body
integer
Default: 0
Enum: 0 1

whether to detect human bodies on the image.

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

whether to estimate head pose in the image. The head pose is represented by pitch, yaw and roll angles.

Not supported with warped images (see warped_image or image_type parameter).

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

whether to estimate emotions in the image. The probability of the following emotions is estimated: "anger", "disgust", "fear", "happiness", "sadness", "surprise", "neutral".

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

whether to estimate mask in the image. The probability of the following masks states is estimated: "medical_mask", "missing", "occluded".

The estimated probability with the highest score is returned in the "predominant mask" parameter.

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

whether to estimate glasses in the image. One of the following parameters is returned: "eyeglasses", "sunglasses", "no_glasses".

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

whether to estimate liveness in the image. The "quality" and "score" probabilities are estimated. Based on these probabilities, the following result is returned: "real", "spoof", "unknown".

Liveness V2 is utilized for this estimation. See "Administrator’s manual" for details about Liveness V2 requirements.

Webcam or selfie photos are required. Otherwise the result may be incorrect.

Liveness v.2 licensing feature is required to be enabled to perform liveness estimation.

Liveness estimation is not supported for samples (warped images). The image_type parameter should be set to "0".

estimate_landmarks68
integer (detect_landmarks68)
Default: 0
Enum: 0 1

whether to detect basic 68-point facial landmarks in the image.

Not supported with warped images (see warped_image or image_type parameter).

estimate_landmarks5
integer (detect_landmarks5)
Default: 0
Enum: 0 1

whether to detect basic 5-point facial landmarks in the image.

Not supported with warped images (see warped_image or image_type parameter).

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

whether to estimate input face image quality. Each of the following probabilities is estimated: "darkness", "light", "blurriness", "illumination", "specularity".

The quality factor is estimated for each probability. It's value is in the range [0..1] where 0 corresponds to low quality and 1 to high quality.

Note. Face recognition is not greatly affected by uneven illumination or high specularity.

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

whether to estimate gaze in the image. The gaze is represented by yaw angle and pitch angle for both eyes at once.

Not supported with warped images (see warped_image or image_type parameter).

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

whether to estimate eye attributes in the image. The "right_eye" and "left_eye" parameters are estimated, which contain the "state" (opened, closed or occluded) and "iris_landmarks" parameters.

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

whether to estimate mouth attributes in the image. Each of the following probabilities is estimated: "opened", "occluded", "smile", "score".

estimate_face_descriptor
integer (extract_descriptor)
Default: 1
Enum: 0 1
Example: estimate_face_descriptor=1

whether to estimate face descriptor(s).

estimate_basic_attributes
integer (extract_basic_attributes)
Default: 0
Enum: 0 1

whether to estimate face basic attributes (gender, age, ethnicity).

estimate_body_descriptor
integer (extract_descriptor)
Default: 1
Enum: 0 1
Example: estimate_body_descriptor=1

whether to create human body descriptor(s).

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

whether to create a human body warped image in the Base64 format.

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

whether to create a face warped image in the Base64 format.

aggregate_attributes
integer (aggregate_attributes)
Default: 0

whether to aggregate face/body attributes (descriptor for face/body and basic attributes for face), as well as mask states, emotions and liveness parameters. Aggregation will be performed only if the appropriate parameters for extracting attributes and/or estimating the mask states, emotions and liveness are enabled.

If set, all extracted attributes and mask states, emotions and liveness parameters from each image will be aggregated and displayed in the "aggregate_estimations" field of the response body as single objects for all images.

Otherwise, all extracted face/body attributes and mask states, emotions and liveness parameters from each image will be displayed in the "estimations" field of the response body as separate objects for corresponding images.

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]
Example: pitch_threshold=180

maximum deviation pitch angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if pitch angle filtration is not required.

When the value is set to "0", all the images are filtered.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]
Example: roll_threshold=180

maximum deviation roll angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if roll angle filtration is not required.

When the value is set to "0", all the images are filtered.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]
Example: yaw_threshold=180

maximum deviation yaw angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if yaw angle filtration is not required.

When the value is set to "0", all the images are filtered.

score_threshold
number (score_threshold) [ 0 .. 1 ]
Default: 0
Example: score_threshold=0.7

Descriptor quality score threshold. The higher the quality score for the image, the better the extraction results.

All the attributes with a 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).

Consult VisionLabs about the recommended value of this parameter.

Note! This parameter is not related to the image quality estimated in the detect request (estimate_quality request parameter).

mask_states
Array of integers (mask_states) non-empty
Items Enum: 1 2 3
Example: mask_states=2&mask_states=3

filter by mask states.

mask state value
missing 1
medical_mask 2
occluded 3
liveness_states
Array of integers (liveness_states) non-empty
Items Enum: 0 1 2
Example: liveness_states=1

filter by liveness states.

liveness state value
spoof 0
real 1
unknown 2
use_exif_info
integer
Default: 1
Enum: 0 1
Example: use_exif_info=1

whether to try to auto orient image based on EXIF data

The processed image should have EXIF data, otherwise auto orientation will not be performed.

Has no effect with tiff images (they're always auto oriented).

Ignored with warped images (see warped_image or image_type parameter).

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Accept request header.

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

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

Content-Type
string
Enum: "application/json" "multipart/form-data" "image/jpeg" "image/png" "image/bmp" "image/x-portable-pixmap" "image/tiff" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-portable-pixmap-base64"
Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
Example
{
  • "images_estimations": [
    ]
}

sdk options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

iso

iso resource

The resource performs a visual examination of frontal type images based on ISO/IEC 19794-5 standard. This means that the images that have passed the validation are standardized and attributes of the person's face meet the established requirements. For more information on the requirements for face attributes in the image, see ISO/IEC 19794-5 Clauses 7-10.

The output JSON contains the result of the check for each estimator. The image check is considered successful if the set of these results complies with the ISO standard.

The order of input images is corresponding to elements order in output JSON. If an image is broken, the resource will return an error for this image and other images will be correctly processed.

query Parameters
image_type
integer
Default: 0
Enum: 0 1

image type of input image. 0 - raw image, 1 - face warped image

multiface_policy
integer (iso_multiface_policy)
Default: 0
Enum: 0 1 2

multiple face detection policy:

  • 0 - do not process images with several detected faces.

    If detect_body is enabled, the system will attempt to detect a human body related to the detected face. If a human body is detected, its detection will be associated with the same event as the face.

    If there is no face detected in the image, no human body detections will be returned. Thus there will be no human body detection returned if detect_face is disabled.

  • 1 - process images with several detected faces and/or human bodies.

    If detect_body is enabled, all the detections of human bodies will be returned. Face detection and human body detection of the same person will be associated with the same event.

    The detections of human bodies are returned even if there were no faces found.

  • 2 - get the best face detection from the image. A single face of the best quality is detected in the image.

    If detect_body is enabled, the system will attempt to detect a human body related to the detected face. If a human body is detected, its detection will be associated with the same event as the face.

    If there is no face detected in the image, no human body detections will be returned. Thus there will be no human body detection returned if detect_face is disabled.

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 for 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 they are. Please refer to JEITA CP-3451 EXIF specification for details.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Accept request header.

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

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

Content-Type
string
Enum: "application/json" "multipart/form-data" "image/jpeg" "image/png" "image/bmp" "image/x-portable-pixmap" "image/tiff" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-portable-pixmap-base64"
Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
Example
{
  • "images": [
    ]
}

samples

detect faces

Detect faces in input images.

The request enables you to detect faces in input images, create samples, and estimate face properties.

You can specify thresholds for the head angles. If a head angle exceeds the specified threshold the image is not processed.

The estimated face properties are not saved to the Faces database. They are only returned in the response.

query Parameters
multiface_policy
integer (multiface_policy)
Default: 1
Enum: 0 1 2

multiple face detection policy:

  • 0 - multiple face detection not allowed

  • 1 - multiple face detection allowed

  • 2 - get only best face detection from the image

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

whether to estimate head pose in the image. The head pose is represented by pitch, yaw and roll angles.

Not supported with warped images (see warped_image or image_type parameter).

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

whether to estimate emotions in the image. The probability of the following emotions is estimated: "anger", "disgust", "fear", "happiness", "sadness", "surprise", "neutral".

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

whether to estimate mask in the image. The probability of the following masks states is estimated: "medical_mask", "missing", "occluded".

The estimated probability with the highest score is returned in the "predominant mask" parameter.

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

whether to detect basic 68-point facial landmarks in the image. Not supported with warped images (see warped_image parameter).

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 for 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 they are. Please refer to JEITA CP-3451 EXIF specification for details.

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

whether to estimate input face image quality. Each of the following probabilities is estimated: "darkness", "light", "blurriness", "illumination", "specularity".

The quality factor is estimated for each probability. It's value is in the range [0..1] where 0 corresponds to low quality and 1 to high quality.

Note. Face recognition is not greatly affected by uneven illumination or high specularity.

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

whether to estimate gaze in the image. The gaze is represented by yaw angle and pitch angle for both eyes at once.

Not supported with warped images (see warped_image or image_type parameter).

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

whether to estimate eye attributes in the image. The "right_eye" and "left_eye" parameters are estimated, which contain the "state" (opened, closed or occluded) and "iris_landmarks" parameters.

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

whether to estimate mouth attributes in the image. Each of the following probabilities is estimated: "opened", "occluded", "smile", "score".

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]
Example: pitch_threshold=180

maximum deviation pitch angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if pitch angle filtration is not required.

When the value is set to "0", all the images are filtered.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]
Example: roll_threshold=180

maximum deviation roll angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if roll angle filtration is not required.

When the value is set to "0", all the images are filtered.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]
Example: yaw_threshold=180

maximum deviation yaw angle from 0. If the estimated value is equal or less than the threshold, the image is filtered.

Remove this parameter from the query, or set the parameter value to 180 if yaw angle filtration is not required.

When the value is set to "0", all the images are filtered.

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

whether an input image is a sample or not.

use_exif_info
integer
Default: 1
Enum: 0 1
Example: use_exif_info=1

whether to try to auto orient image based on EXIF data

The processed image should have EXIF data, otherwise auto orientation will not be performed.

Has no effect with tiff images (they're always auto oriented).

Ignored with warped images (see warped_image or image_type parameter).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

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

detector options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

save face/body sample

Save face or body sample to the storage.

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/x-portable-pixmap"
Request Body schema:
One of
string <binary> (face_sample)

an image generated by VisionLabs algorithms.

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/samples/faces"
response = requests.post(url, data=image, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "sample_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/samples/bodies/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

face/body samples options

get options for the resource

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get face/body sample

Get face or body sample by ID.

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/samples/faces"
sampleId = requests.post(url, data=image, headers=headers).json()["sample_id"]

# get sample
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/samples/faces/{sampleId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

check to exist a face/body sample

Check existence of the face or body sample with id=sample_id.

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/samples/faces"
sampleId = requests.post(url, data=image, headers=headers).json()["sample_id"]

# get sample
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/samples/faces/{sampleId}"
response = requests.head(url, headers=headers)

print(response.status_code)

remove face/body sample

Remove face or body sample by ID.

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/samples/faces"
sampleId = requests.post(url, data=image, headers=headers).json()["sample_id"]

# get sample
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/samples/faces/{sampleId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

face/body sample options

get options for the resource

path Parameters
samples_type
required
string
Enum: "faces" "bodies"

Samples type.

sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

get sample | previous version Deprecated

Get sample by ID using previous API version

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

check to exist a sample | previous version Deprecated

Check existence of the sample with id=sample_id using previous API version.

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

remove sample | previous version Deprecated

Remove sample by ID using previous API version.

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

sample options | previous version Deprecated

get options for the resource using previous API version

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

get sample | legacy Deprecated

Get a face sample by ID.

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

check to exist a face sample | legacy Deprecated

Check existence of the sample with id=sample_id.

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

remove face sample | legacy Deprecated

Remove sample by ID.

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

face sample options | legacy Deprecated

get options for the resource

path Parameters
sample_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

images

create images

save images with unique id

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

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

Content-Type
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/tiff" "image/x-portable-pixmap"

type of transferring image

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema:
string <binary> (binary_image)

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/images"
response = requests.post(url, data=image, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "image_id": "141d2706-8baf-433b-82eb-8c7fada847da",
  • "url": "/6/images/141d2706-8baf-433b-82eb-8c7fada847da"
}

images options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

head image

check image exists

path Parameters
image_id
required
string <uuid> (image_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

image ID.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/images"
imageId = requests.post(url, data=image, headers=headers).json()["image_id"]

# get image
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/images/{imageId}"
response = requests.head(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

delete image

Delete an image

path Parameters
image_id
required
string <uuid> (image_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

image ID.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/images"
imageId = requests.post(url, data=image, headers=headers).json()["image_id"]

# get image
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/images/{imageId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

get image

receive an origin image

path Parameters
image_id
required
string <uuid> (image_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

image ID.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("face_warp.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/images"
imageId = requests.post(url, data=image, headers=headers).json()["image_id"]

# get image
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/images/{imageId}"
response = requests.get(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 13003,
  • "desc": "Object not found",
  • "detail": "Image with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

image options

get options for the resource

path Parameters
image_id
required
string <uuid> (image_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

image ID.

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

objects

create objects

save object with unique id

header Parameters
Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

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

Content-Type
required
string
Enum: "application/json" "application/pdf" "application/zip" "text/plain"

type of transferring information, available - text, json, zip, pdf

Request Body schema:
string (application_json)

content type is application/json

Responses

Request samples

Content type
{
  • "content": "json"
}

Response samples

Content type
application/json
{
  • "object_id": "141d2706-8baf-433b-82eb-8c7fada847da",
  • "url": "/6/objects/141d2706-8baf-433b-82eb-8c7fada847da"
}

objects options

get options for the resource

header Parameters
Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get object

receiving objects

path Parameters
object_id
required
string <uuid> (object_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

object ID.

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

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

Accept
string (objects_accept)
Enum: "application/json" "text/plain" "application/zip" "application/pdf"

acceptable type of recieving data

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create objects
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "text/plain",
}

url = f"{baseUri}/objects"
objectId = requests.post(url, data="example", headers=headers).json()["object_id"]

# get object
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/objects/{objectId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.text)

Response samples

Content type
{
  • "json": "example"
}

head object

check object exists

path Parameters
object_id
required
string <uuid> (object_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

object ID.

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

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

Accept
string (objects_accept)
Enum: "application/json" "text/plain" "application/zip" "application/pdf"

acceptable type of recieving data

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create object
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "text/plain",
}

url = f"{baseUri}/objects"
objectId = requests.post(url, data="example", headers=headers).json()["object_id"]

# check objects
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/objects/{objectId}"
response = requests.head(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 13007,
  • "desc": "Object not found",
  • "detail": "Object with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

delete object

Delete object

path Parameters
object_id
required
string <uuid> (object_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

object ID.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create object
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "text/plain",
}

url = f"{baseUri}/objects"
objectId = requests.post(url, data="example", headers=headers).json()["object_id"]

# get object
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/objects/{objectId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

object options

get options for the resource

path Parameters
object_id
required
string <uuid> (object_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 141d2706-8baf-433b-82eb-8c7fada847da

object ID.

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

attributes

extract attributes

Extract descriptors and basic attributes from samples.

All the extracted attributes are temporary.

Temporary attributes have a TTL (time to live) and will be removed from the database after the specified period.

query Parameters
score_threshold
number (score_threshold) [ 0 .. 1 ]
Default: 0
Example: score_threshold=0.7

Descriptor quality score threshold. The higher the quality score for the image, the better the extraction results.

All the attributes with a 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).

Consult VisionLabs about the recommended value of this parameter.

Note! This parameter is not related to the image quality estimated in the detect request (estimate_quality request parameter).

extract_descriptor
integer (extract_descriptor)
Default: 1
Enum: 0 1
Example: extract_descriptor=1

whether to extract face descriptor(s).

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

whether to extract basic attributes (gender, age, ethnicity).

aggregate_attributes
integer (aggregate_attributes)
Default: 0

whether to aggregate face attributes (descriptor and basic attributes). Aggregation will only be performed together with the extract_descriptor and/or extract_basic_attributes parameters.

If set, all extracted attributes from each image will be aggregated and stored as single objects.

Otherwise, all extracted attributes from each image will be stored for each sample as separate objects.

ttl
integer [ 1 .. 86400 ]
Default: 300

lifetime for temporary attribute (seconds)

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
Array ()
string <uuid> (sample_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

sample ID.

Responses

Request samples

Content type
application/json
[
  • "f9f03668-27e3-4e23-9b55-681e5927905e",
  • "4967ccb7-b521-43b5-93ba-a0d266631bb2",
  • "dd98cf9c-ddf3-4962-a3c5-e8bd540a4fc7"
]

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    },
  • {
    }
]

extractor options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

create temporary attribute

New temporary attributes creation.

Note. Use this request when you need to add basic attributes or descriptors from external storage. Otherwise, use the extract attributes request.

All the extracted attributes are temporary.

Temporary attributes have a TTL (time to live) and will be removed from the database after the specified period.

query Parameters
ttl
integer [ 1 .. 86400 ]
Default: 300

lifetime for temporary attribute (seconds)

header Parameters
Content-Type
string
Enum: "application/json" "multipart/form-data"

content type is application/json or multipart/form-data.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

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

Request Body schema:
One of
required
Array of descriptor_data (object) or sdk_descriptor_base64 (string) (face_descriptors) non-empty

list of descriptors with versions. Each descriptor is aggregated from the provided samples

face_descriptor_samples
Array of strings <uuid> (attributes_samples) >= 0 items unique
Default: []

list of uniqie sample IDs which are resources for the estimated attributes.

WARNING: if the user does not set any attributes samples, faces with such attributes will be skipped during the process of updating attributes using a new estimation algorithm.

required
object (basic_attributes)

basic attributes

basic_attributes_samples
Array of strings <uuid> (attributes_samples) >= 0 items unique
Default: []

list of uniqie sample IDs which are resources for the estimated attributes.

WARNING: if the user does not set any attributes samples, faces with such attributes will be skipped during the process of updating attributes using a new estimation algorithm.

Responses

Request samples

Content type
Example
{
  • "face_descriptors": [
    ],
  • "face_descriptor_samples": [
    ],
  • "basic_attributes": {
    },
  • "basic_attributes_samples": [
    ]
}

Response samples

Content type
application/json
{
  • "attribute_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/attributes/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get temporary attributes

Get temporary attributes by IDs.

For each attribute:

  • If the attribute TTL has not expired, the attribute data is returned.

  • If the TTL has expired, no data is returned for this attribute in the response.

query Parameters
attribute_ids
required
string <list of uuid>

list of comma-separated attribute ids.

targets
string <comma-separated items>
Default: "create_time, attribute_id, account_id, face_descriptor_samples, basic_attributes_samples, face_descriptor, basic_attributes_samples"
Example: targets=basic_attributes,basic_attributes_samples,account_id

list of comma-separated temporary attributes targets. All targets are available by default.

descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58 59
Example: descriptor_version=56

descriptor version returned in the response. By default, the LUNA PLATFORM default descriptor is used version.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create attribute
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 0,
        "ethnicity": 3,
    },
}

url = f"{baseUri}/attributes"
attributeId = requests.post(url, json=payload, headers=headers).json()["attribute_id"]

# get attributes
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

params = {
    "attribute_ids": [
        attributeId,
    ],
    "targets": "basic_attributes,basic_attributes_samples,account_id",
}

url = f"{baseUri}/attributes"
response = requests.get(
    url, headers=headers, params=params
)

print(response.status_code)
print(response.json())

Response samples

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

temporary attributes options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get temporary attribute

Get temporary attribute by ID.

If the attribute TTL has not expired, the attribute data is returned.

Otherwise, the "Attributes not found" error is returned.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

id of the temporary attribute.

query Parameters
descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58 59
Example: descriptor_version=56

descriptor version returned in the response. By default, the LUNA PLATFORM default descriptor is used version.

targets
string <comma-separated items>
Default: "create_time, attribute_id, account_id, face_descriptor_samples, basic_attributes_samples, face_descriptor, basic_attributes_samples"
Example: targets=basic_attributes,basic_attributes_samples,account_id

list of comma-separated temporary attributes targets. All targets are available by default.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create attribute
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 1,
        "ethnicity": 3,
    },
}

url = f"{baseUri}/attributes"
attributeId = requests.post(url, json=payload, headers=headers).json()["attribute_id"]

# get attributes
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/attributes/{attributeId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
Example
{
  • "create_time": "2021-08-11T14:57:18.416928+03:00",
  • "attribute_id": "7fdf9225-3c06-4c21-b774-8bea99bcce20",
  • "account_id": "0d1cc36e-d719-4f54-8abe-4e5e0cb1f43c",
  • "face_descriptor_samples": [
    ],
  • "basic_attributes_samples": [
    ],
  • "face_descriptor": "2xQ2gprbMUePw1s9gw9fvA==",
  • "basic_attributes": {
    }
}

check temporary attribute

check temporary attribute existence.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

id of the temporary attribute.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create attribute
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 1,
        "ethnicity": 3,
    },
}

url = f"{baseUri}/attributes"
attributeId = requests.post(url, json=payload, headers=headers).json()["attribute_id"]

# get attributes
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/attributes/{attributeId}"
response = requests.head(url, headers=headers)

print(response.status_code)

delete attribute

Delete the attribute by its id.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

id of the temporary attribute.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

# create attribute
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 1,
        "ethnicity": 3,
    },
}

url = "http://127.0.0.1:5000/6/attributes"
attributeId = requests.post(url, json=payload, headers=headers).json()["attribute_id"]

# get attributes
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"http://127.0.0.1:5000/6/attributes/{attributeId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

temporary attributes attribute options

get options for the resource

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

id of the temporary attribute.

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get temporary attribute samples

Get all the temporary attribute samples by the attribute ID.

If the attribute TTL has not expired, the attribute data is returned.

Otherwise, the "Attributes not found" error is returned.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: b668c4a5-2191-476e-a261-3b4f9ce2e25e

id of the temporary attribute.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("image.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/detector"
sampleId = requests.post(url, data=image, headers=headers).json()["images"][0]["detections"]["samples"][0]["face"]["sample_id"]

# exreact attr
# create attribute
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 1,
        "ethnicity": 3,
    },
    "basic_attributes_samples": [
        sampleId,
    ],
}

url = f"{baseUri}/attributes"
attributeId = requests.post(url, json=payload, headers=headers).json()["attribute_id"]

# get attributes by id
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/attributes/{attributeId}/samples"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

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

faces

create face

Create a new face.

The face can be attached to one or several lists.

You can create a new face using a temporary attribute ID or using external attribute data (descriptors and/or basic attributes).

You can also create a face without any attributes specified.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

Format of a request body data

Request Body schema:
attribute_set_by_attribute_id (object) or (attribute_no_account (attribute_with_descriptors_and_basic_attributes_no_account (object) or attribute_with_basic_attributes_no_account (object) or attribute_with_descriptors_no_account (object))) (face_attribute)

face attributes.

You can specify attributes for the face using one of several ways:

  • by specifying the attribute ID of a temporary attribute

  • by specifying descriptors and basic attributes (with or without samples)

  • by specifying descriptors (with or without samples)

  • by specifying basic attributes (with or without samples)

    The last three ways are used when you need to create a face using data stored in external storage.

external_id
string (face_external_id) <= 36 characters
Default: ""

user-defined external ID for the face. External ID can be used to link several faces which belong to one person.

user_data
string (face_user_data) <= 128 characters
Default: ""

user data associated with face

avatar
string <uri-reference> (avatar) <= 256 characters
Default: ""

avatar is a visual representation of a face.

The avatar can be used in the user interface.

You can use a sample or an external image as the avatar.

lists
Array of strings <uuid> (list_id) non-empty

luna lists for linking face with them.

event_id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

the event ID associated with the face creation.

Responses

Request samples

Content type
Example
{}

Response samples

Content type
application/json
{
  • "face_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/faces/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get faces

Get faces according to filters.

query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

event_id
string <uuid> (event_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: event_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

the event ID associated with the face creation

face_id__lt
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: face_id__lt=8950722f-3fd4-4223-b48f-03f95f0e8dfb

face id upper excluded bound

face_id__gte
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: face_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

face id lower included bound

face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated face ids.

external_ids
string
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated external ids.

user_data
string
Example: user_data=user_data_text

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

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

id of a list that contains faces.

targets
string
Enum: "face_id" "account_id" "event_id" "user_data" "create_time" "external_id" "avatar" "lists"
Example: targets=face_id,user_data

Comma-separated list of face fields. If set, each face from result will contain only specified fields, otherwise, faces with all the fields will be returned.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces"
params = {
    "create_time__gte": "2018-08-11T09:11:41.674Z",
    "user_data": "face",
    "targets": "face_id,account_id,event_id,user_data,create_time",
}

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

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

delete faces

Delete several faces.

query Parameters
ignore
integer (int01)
Default: 0
Enum: 0 1

whether to ignore the error if a face to be deleted does not exist

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
face_ids
required
Array of strings <uuid> (face_id) non-empty

IDs of faces for removal

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('faces' was unexpected)'"
}

faces options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get face count

Count faces according to the filters.

query Parameters
create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated face ids.

face_id__lt
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: face_id__lt=8950722f-3fd4-4223-b48f-03f95f0e8dfb

face id upper excluded bound

face_id__gte
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: face_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

face id lower included bound

event_id
string <uuid> (event_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: event_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

the event ID associated with the face creation

external_ids
string
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated external ids.

user_data
string
Example: user_data=user_data_text

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

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

id of a list that contains faces.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/count"
params = {
    "create_time__gte": "2018-08-11T09:11:41.674Z",
    "user_data": "face",
}
response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "faces_count": 7
}

faces count options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get count of faces with attributes

count faces with attributes

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/attributes/count"

response = requests.get(
    url,
    headers=headers,
)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "faces_count": 7
}

get count of faces with attributes options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get face

Get face by ID.

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

ID of the face (face_id received in the "create face" request).

query Parameters
targets
string
Enum: "face_id" "account_id" "event_id" "user_data" "create_time" "external_id" "avatar" "lists"
Example: targets=face_id,user_data

Comma-separated list of face fields. If set, each face from result will contain only specified fields, otherwise, faces with all the fields will be returned.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces"
faceId = requests.post(url, headers=headers).json()["face_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/faces/{faceId}"
response = requests.get(
    url,
    headers=headers,
)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "face_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c6",
  • "account_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "event_id": "f9687459-986b-406d-9c1f-0d6289be5256",
  • "user_data": "fox1991",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
  • "lists": [
    ]
}

patch face

Update face fields: user_data, external_id, event_id, avatar.

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

ID of the face (face_id received in the "create face" request).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
external_id
string <= 36 characters

user-defined external ID for the face.

event_id
string <uuid> Nullable ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

event ID.

user_data
string <= 128 characters

user data associated with face

avatar
string <uri-reference> (avatar) <= 256 characters
Default: ""

avatar is a visual representation of a face.

The avatar can be used in the user interface.

You can use a sample or an external image as the avatar.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('userdata' was unexpected)'"
}

remove face

Remove face by ID.

When a face is removed, attributes (descriptors and basic attributes) linked to the face are deleted. Samples linked to the face are not deleted.

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

ID of the face (face_id received in the "create face" request).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}
url = f"{baseUri}/faces"
faceId = requests.post(
    url,
    headers=headers,
).json()["face_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/{faceId}"
response = requests.delete(
    url,
    headers=headers,
)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

check to exist a face

Check existence of the face with id=face_id

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

ID of the face (face_id received in the "create face" request).

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces"
faceId = requests.post(
    url,
    headers=headers,
).json()["face_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/{faceId}"
response = requests.head(
    url,
    headers=headers,
)

print(response.status_code)

face options

get options for the resource

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

ID of the face (face_id received in the "create face" request).

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

face attributes

put face attribute

Put face attribute.

This request changes all the attribute data corresponding to the specified face.

The attribute can be specified by temporary attribute ID or using external attribute data (descriptors and/or basic attributes).

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

ID of the face (face_id received in the "create face" request).

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
One of
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

attribute ID. This ID links the descriptor, basic attributes, and samples received from a single image.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('userdata' was unexpected)'"
}

get face attribute

Get face attribute by ID.

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

ID of the face (face_id received in the "create face" request).

query Parameters
targets
string <comma-separated items>
Default: "create_time,basic_attributes,basic_attributes_samples,face_descriptor,face_descriptor_samples"

list of comma-separated temporary attributes targets. Available targets: create_time, basic_attributes, basic_attributes_samples, face_descriptor, face_descriptor_samples

descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58 59
Example: descriptor_version=56

descriptor version returned in the response. By default, the LUNA PLATFORM default descriptor is used version.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import base64

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("image.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/detector"
sampleId = requests.post(url, data=image, headers=headers).json()["images"][0]["detections"]["samples"][0]["face"]["sample_id"]

# create attribute
with open("descriptor56", "rb") as file:
    descriptor = base64.b64encode(file.read()).decode()

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
params = {
    "ttl": 600,
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 0,
        "ethnicity": 3,
    },
    "basic_attributes_samples": [
        sampleId,
    ],
    "face_descriptor_samples": [
        sampleId,
    ],
    "face_descriptors": [
        {"descriptor": descriptor, "version": 56},
    ],
}
url = f"{baseUri}/attributes"
attributeId = requests.post(
    url, json=payload, headers=headers, params=params
).json()["attribute_id"]

# create face
payload = {
    "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
    "attribute": {"attribute_id": attributeId},
}
headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}
url = f"{baseUri}/faces"
faceId = requests.post(
    url,
    headers=headers,
    json=payload,
).json()["face_id"]

# get face attribute by ID
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/{faceId}/attributes"
response = requests.get(
    url,
    headers=headers,
)

print(response.status_code)
print(response.json())

Response samples

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

delete face attribute

Remove face attribute by ID.

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

ID of the face (face_id received in the "create face" request).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import base64

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}
with open("image.jpg", "rb") as image_file:
    image = image_file.read()
url = f"{baseUri}/detector"
sampleId = requests.post(url, data=image, headers=headers).json()["images"][0]["detections"]["samples"][0]["face"]["sample_id"]

# create attribute
with open("descriptor56", "rb") as file:
    descriptor = base64.b64encode(file.read()).decode()

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
params = {
    "ttl": 600,
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 0,
        "ethnicity": 3,
    },
    "basic_attributes_samples": [
        sampleId,
    ],
    "face_descriptor_samples": [
        sampleId,
    ],
    "face_descriptors": [
        {"descriptor": descriptor, "version": 56},
    ],
}
url = f"{baseUri}/attributes"
attributeId = requests.post(
    url, json=payload, headers=headers, params=params
).json()["attribute_id"]

payload = {
    "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
    "attribute": {"attribute_id": attributeId},
}

# create face
headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}
url = f"{baseUri}/faces"
faceId = requests.post(
    url,
    headers=headers,
    json=payload,
).json()["face_id"]

# get face attribute by ID
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/{faceId}/attributes"
response = requests.delete(
    url,
    headers=headers,
)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

faces attributes options

get options for the resource

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

ID of the face (face_id received in the "create face" request).

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get face attribute samples

Get face attribute samples by face ID.

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

ID of the face (face_id received in the "create face" request).

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import base64

baseUri = "http://127.0.0.1:5000/6"

# create sample
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
}

with open("image.jpg", "rb") as image_file:
    image = image_file.read()

url = f"{baseUri}/detector"
sampleId = requests.post(url, data=image, headers=headers).json()["images"][0]["detections"]["samples"][0]["face"]["sample_id"]

# create attribute
with open("descriptor56", "rb") as file:
    descriptor = base64.b64encode(file.read()).decode()

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
params = {
    "ttl": 600,
}
payload = {
    "basic_attributes": {
        "age": 29,
        "gender": 0,
        "ethnicity": 3,
    },
    "basic_attributes_samples": [
        sampleId,
    ],
    "face_descriptor_samples": [
        sampleId,
    ],
    "face_descriptors": [
        {"descriptor": descriptor, "version": 56},
    ],
}
url = f"{baseUri}/attributes"
attributeId = requests.post(
    url, json=payload, headers=headers, params=params
).json()["attribute_id"]

# create face
payload = {
    "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
    "attribute": {"attribute_id": attributeId},
}
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces"
faceId = requests.post(
    url,
    headers=headers,
    json=payload,
).json()["face_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/faces/{faceId}/attributes/samples"
response = requests.get(
    url,
    headers=headers,
)

print(response.status_code)
print(response.json())

Response samples

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

faces attributes samples options

get options for the resource

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

ID of the face (face_id received in the "create face" request).

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

lists

create list

Create a new list.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

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

user data associated with list

Responses

Request samples

Content type
application/json
{
  • "user_data": "list of good persons"
}

Response samples

Content type
application/json
{
  • "list_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/lists/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get lists

Get lists according to the filters.

query Parameters
create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for list create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for list create_time.

last_update_time__lt
string <date-time> (time)
Example: last_update_time__lt=2018-08-11T09:11:41.674Z

upper excluded bound for list last_update_time.

last_update_time__gte
string <date-time> (time)
Example: last_update_time__gte=2018-08-11T09:11:41.674Z

lower included bound for list last_update_time.

user_data
string
Example: user_data=user_data_text

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

user_data__eq
string
Example: user_data__eq=user_data_text

find all objects with same user_data.

list_ids
string <list of uuid>

list of comma-separated list ids.

list_id__lt
string <uuid>

list id upper excluding boundary.

list_id__gte
string <uuid>

list id lower including boundary.

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

params = {
    "user_data": "good",
    "page_size": 20,
    "create_time__gte": "2020-10-10T09:11:41.674Z",
}
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists"
response = requests.get(url, params=params, headers=headers)

print(response.status_code)
print(response.json())

Response samples

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

delete lists

Delete several lists.

query Parameters
with_faces
integer (int01)
Default: 0
Enum: 0 1

whether to delete list with all its faces

header Parameters
Content-Type
string
Value: "application/json"

content type is application/json.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
list_ids
required
Array of strings <uuid> (list_id) non-empty

list ids for removal

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('faces' was unexpected)'"
}

lists options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get list count

Count lists according to the filters.

query Parameters
user_data
string
Example: user_data=user_data_text

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

user_data__eq
string
Example: user_data__eq=user_data_text

find all objects with same user_data.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for list create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for list create_time.

last_update_time__lt
string <date-time> (time)
Example: last_update_time__lt=2018-08-11T09:11:41.674Z

upper excluded bound for list last_update_time.

last_update_time__gte
string <date-time> (time)
Example: last_update_time__gte=2018-08-11T09:11:41.674Z

lower included bound for list last_update_time.

list_ids
string <list of uuid>

list of comma-separated list ids.

list_id__lt
string <uuid>

list id upper excluding boundary.

list_id__gte
string <uuid>

list id lower including boundary.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# get list according to the filters
params = {
    "user_data": "good",
    "create_time__gte": "2020-10-10T09:11:41.674Z",
    "last_update_time__gte": "2020-10-10T09:11:41.674Z",
}
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists/count"
response = requests.get(url, params=params, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "lists_count": 3
}

lists count options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get list

Get list by id

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

list id (list_id received in the "create list" request)

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists"
listId = requests.post(url, headers=headers).json()["list_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists/{listId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "list_id": "c004aae2-f191-4a1a-9d2a-e5894f8cecbf",
  • "user_data": "good guys",
  • "account_id": "c004aae2-f191-4a1a-9d2a-e5894f8cecbf",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "last_update_time": "2018-08-11T09:11:41.674Z"
}

check list existence

Check existence of the list with id=list_id.

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

list id (list_id received in the "create list" request)

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists"
listId = requests.post(url, headers=headers).json()["list_id"]

# check list
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists/{listId}"
response = requests.head(url, headers=headers)

print(response.status_code)
print(response.json())

update list

Update the user_data field of the list.

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

list id (list_id received in the "create list" request)

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

user data associated with list

Responses

Request samples

Content type
application/json
{
  • "user_data": "list of good persons"
}

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

delete list

Delete list by id

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

list id (list_id received in the "create list" request)

query Parameters
with_faces
integer (int01)
Default: 0
Enum: 0 1

whether to delete list with all its faces

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# create list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/lists"
listId = requests.post(url, headers=headers).json()["list_id"]

# delete list
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
params = {"with_faces": 1}
url = f"{baseUri}/lists/{listId}"
response = requests.delete(url, params=params, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

list options

get options for the resource

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

list id (list_id received in the "create list" request)

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

attach/detach faces to the list

Attach or detach faces to the list.

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

list id (list_id received in the "create list" request)

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
action
required
string
Enum: "attach" "detach"

expected action with list and faces.

face_ids
required
Array of strings <uuid> (face_id) non-empty

faces to attach or detach to/from list.

Responses

Request samples

Content type
application/json
{
  • "action": "attach",
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

link options

get options for the resource

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

list id (list_id received in the "create list" request)

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

matcher

matching faces

Performs matching of the given references with the given candidates.

Note! Descriptors must be extracted for reference(s) and candidate(s). Objects without descriptors cannot be matched.

The sources for candidates are faces, attributes and events. See the "compare two faces using their IDs", "compare two events using their IDs", and "compare events using filters" examples.

You can specify the "list_id" filter of the "faces" candidate to perform matching by the specified list. See the "search by list and creation time" examples.

The sources for references are faces, events, attributes, external IDs of faces, or descriptors (raw, SDK format, or binary XPK format).

Matching results are returned for the candidates that correspond to the specified filters. If none of the candidates corresponds to the filters (for example, a non-existent ID is set in the "event_ids" field or the "face_ids" field), there will be no matching result and no error returned. The result field will be empty. See the "nonexistent references errors" examples.

If a non-existent reference is set (for example, a non-existent ID is set in the "event_id" field or the "face_id" field), the corresponding error is returned. See the "no ID for reference face found" response example.

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

Format of a request body data

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Request Body schema: application/json
required
Array of candidate_face (object) or candidate_event (object) or candidate_attribute (object) [ 0 .. 30 ] items

candidates for matching

required
Array of face_reference (object) or event_reference (object) or attribute_reference (object) or external_face_reference (object) or external_event_reference (object) or track_event_reference (object) or xpk_reference (object) or sdk_descriptor_reference (object) or raw_descriptor_reference (object) [ 1 .. 30 ] items

references for matching. Each reference is matched with all the given candidates. You can specify one or several references of one or several types.

Responses

Request samples

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

Response samples

Content type
application/json
Example
[
  • {
    }
]

matcher options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

human body matching

Matcher API allows to submit tasks to a service that searches for human bodies similar to a given reference(s) by matching them. A body attribute descriptor should be extracted for reference(s) and candidate(s).

The sources for references are events or binary descriptor. The sources for candidates is events.

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

Format of a request body data

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Request Body schema: application/json
required
Array of event_reference (object) or external_event_reference (object) or track_event_reference (object) or sdk_descriptor_reference (object) or raw_body_descriptor_reference (object) [ 1 .. 30 ] items

reference list for matching

required
Array of objects (candidate_event) [ 1 .. 30 ] items

candidates for matching

Responses

Request samples

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

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

matcher options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

raw matching

Matcher raw API allows to do similarity calculations for input descriptors.

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

Format of a request body data

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

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 matching

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

candidates for matching

Responses

Request samples

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

Response samples

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

matcher raw options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

handlers

create handler

Create a new handler.

The handler determines the list of rules (policies) for processing of input images.

You can create a dynamic handler by specifying the "is_dynamic" flag. The policies for such handlers are specified during the "create event" request creation. You can set parameters for detecting faces and/or human bodies and extracting attributes. You can set rules for matching these attributes and creating faces from them.

After the handler is created, you should use the "create events" request to process images using the handler.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

description of the handler.

Use it to distinguish the handler from other created handlers and filter handlers using corresponding requests.

object (Policies)

the set of rules, which determine input images processing. Empty policies refer to dynamic handler.

is_dynamic
boolean (is_dynamic)
Default: false

dynamic handler flag. If the value is set to "true", the handler is created without predefined policies.

Use this flag to specify policies for each event created using resource "/handlers/{handler_id}/event". Use the request body schema "multipart/form-data" to specify policies.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "Full handler example",
  • "policies": {
    },
  • "is_dynamic": false
}

Response samples

Content type
application/json
{
  • "handler_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/handlers/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get handlers

Get handlers by filters.

query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

is_dynamic
integer
Default: 0
Enum: 0 1

whether to get only dynamic (1) or non-dynamic (0) handlers

description
string

records with descriptions similar to this parameter will be processed.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

params = {
    "description": "handler",
    "is_dynamic": 1,
    "page": 1,
}

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/handlers"

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

handlers options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get handler count

Count handlers.

query Parameters
description
string

Find all the handlers with description similar to this parameter.

is_dynamic
integer
Default: 0
Enum: 0 1

whether to get only dynamic (1) or non-dynamic (0) handlers

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

params = {
    "description": "handler",
    "is_dynamic": 0,
}

url = f"{baseUri}/handlers/count"

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "handlers_count": 5
}

handler count options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

validate handler policies

Validate handler policies before using them to create or update a handler

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
required
object (Policies)

the set of rules, which determine input images processing. Empty policies refer to dynamic handler.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

get handler

Get handler by ID.

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

handler id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

import requests

baseUri = "http://127.0.0.1:5000/6"

# create handler
headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}
url = f"{baseUri}/handlers"
payload = {"is_dynamic": True}
dynamicHandlerId = requests.post(url, json=payload, headers=headers).json()["handler_id"]

# get handler
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/handlers/{dynamicHandlerId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "handler_id": "de0846a8-09b2-4c6f-8175-99cfae98cf6b",
  • "account_id": "3c3a83c2-c21e-4855-91b5-34e6b63fb12d",
  • "description": "first handler",
  • "policies": {
    },
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "last_update_time": "2018-08-11T09:11:41.674Z",
  • "is_dynamic": false
}

replace handler

Update a handler. You cannot update a part of a handler, so you should specify all the fields for your handler.

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

handler id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

description of the handler.

Use it to distinguish the handler from other created handlers and filter handlers using corresponding requests.

object (Policies)

the set of rules, which determine input images processing. Empty policies refer to dynamic handler.

is_dynamic
boolean (is_dynamic)
Default: false

dynamic handler flag. If the value is set to "true", the handler is created without predefined policies.

Use this flag to specify policies for each event created using resource "/handlers/{handler_id}/event". Use the request body schema "multipart/form-data" to specify policies.

Responses

Request samples

Content type
application/json
{
  • "description": "Handler example",
  • "policies": {
    },
  • "is_dynamic": false
}

Response samples

Content type
application/json
Example
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

check to exist a handler

Check existence of the handler with id=handler_id.

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

handler id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/handlers"

payload = {"is_dynamic": True}
dynamicHandlerId = requests.post(url, json=payload, headers=headers).json()["handler_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/handlers/{dynamicHandlerId}"
response = requests.head(url, headers=headers)

print(response.status_code)

remove handler

Remove handler by id.

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

handler id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/handlers"

payload = {"is_dynamic": True}
dynamicHandlerId = requests.post(url, json=payload, headers=headers).json()["handler_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/handlers/{dynamicHandlerId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 11036,
  • "desc": "Forbidden",
  • "detail": "Luna-Account-Id header is required for requests that change the state of system"
}

handler options

get options for the resource

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

handler id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

events

generate events

Process images and/or raw descriptors using the specified handler and generate events.

Specify the multipart/form-data schema if you need to specify the dynamic handler policies.

If the Events service support is disabled on the server, events will not be saved to the database.

Notes for incoming data:

  • set the image detection time, if necessary, otherwise it will be equal to the request time.
path Parameters
handler_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

handler id

query Parameters
city
string (location_str) <= 36 characters
Example: city=New York

city where an event occurred

area
string (location_str) <= 36 characters
Example: area=Manhattan

area where an event occurred

district
string (location_str) <= 36 characters
Example: district=Midtown

district where an event occurred

street
string (location_str) <= 36 characters
Example: street=West 48th street

street where an event occurred

house_number
string (location_str) <= 36 characters
Example: house_number=220

house number where an event occurred

longitude
number (longitude) [ -180 .. 180 ]
Example: longitude=36.616

longitude in degrees, a part of composite geo position. Geo position is considered as properly specified if both longitude and latitude are set.

latitude
number (latitude) [ -90 .. 90 ]
Example: latitude=55.752

latitude in degrees, a part of composite geo position. Geo position is considered as properly specified if both longitude and latitude are set.

external_id
string (event_external_id) <= 36 characters
Default: ""
Example: external_id=14159261415926

external ID for created faces.

When Unicode symbols (for example, the "+" symbol) are used in "external_id", the string should be encoded. Otherwise, the Unicode symbols will be lost. The "luna3" client library provides the encoding example

user_data
string (face_user_data) <= 128 characters
Default: ""
Example: user_data=face of person

User data for created faces

image_type
integer
Default: 0
Enum: 0 1 2

type of input image. 0 - raw image, 1 - face warped image, 2 - body warped image

aggregate_attributes
integer (aggregate_attributes)
Default: 0

whether to aggregate face/body attributes (descriptor for face/body and basic attributes for face), as well as mask states, emotions and liveness parameters. Aggregation will be performed only if the appropriate parameters for extracting attributes and/or estimating the mask states, emotions and liveness are enabled in the handler.

If set, all extracted attributes and mask states, emotions and liveness parameters from each image will be aggregated and stored in the event as single objects for all images. In the response body, the aggregated attributes of all images will be displayed in the "face_attributes" > "basic_attributes" field, and the aggregated mask state, emotion and Liveness parameters will be displayed in the "aggregate_estimations" field.

Otherwise, all extracted attributes and mask states, emotions and liveness parameters from each image will be stored in the event as separate objects. In the response body, the attributes will be displayed in the "face_attributes" > "basic_attributes" field of the corresponding image, and the mask states, emotions and Liveness parameters will be displayed in the "detections" > "attributes" field of the corresponding image.

source
string (source) <= 128 characters
Example: source=3rd Avenue

Additional information provided by user along with event.

tags
Array of strings (tag) >= 0 items
Example: tags=tag_1,tag_2

comma-separated list of tags. Each event from result will contain all of the given tags. Each tag can be at most 36 characters.

track_id
string (track_id) ^[a-zA-Z0-9_\-]{1,36}$
Example: track_id=useful_track_id_number_1

event track id

use_exif_info
integer
Default: 1
Enum: 0 1
Example: use_exif_info=1

whether to try to auto orient image based on EXIF data

The processed image should have EXIF data, otherwise auto orientation will not be performed.

Has no effect with tiff images (they're always auto oriented).

Ignored with warped images (see warped_image or image_type parameter).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Luna-Event-Time
string <date-time> (time)
Examples:
  • 2018-12-16T15:29:59.300275-08:00 - time with timezone with an offset of -08:00 from UTC (Pacific Standard Time).
  • 2018-12-16T15:29:59.300275Z - utc time. The "Z" suffix denotes a UTC offset of 00:00 (Zulu).

user defined event time. All events will be saved with this time as "create_time".

Format of time is rfc3339. Any other format is ignored.

Luna-Event-End-Time
string <date-time> (time)
Examples:
  • 2018-12-16T15:29:59.300275-08:00 - time with timezone with an offset of -08:00 from UTC (Pacific Standard Time).
  • 2018-12-16T15:29:59.300275Z - utc time. The "Z" suffix denotes a UTC offset of 00:00 (Zulu).

user defined event end time. All events will be saved with this time as "end_time".

Format of time is rfc3339. All other format is ignored.

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" "application/x-sdk-descriptor" "application/x-vl-xpk" "application/x-sdk-descriptor-base64" "applicaition/x-vl-xpk-base64"
Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
Example
{
  • "images": [
    ],
  • "events": [
    ],
  • "filtered_detections": {
    }
}

generate events options

get options for the resource

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

handler id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

save event

Save event which was generated by the user. The event structure is similar to an event from handler response. Input events will send to the Sender also and to plugins. Therefore, these events are the same events except that events were generated an external handler. Handler ID must belong to a dynamic handler.

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

dynamic handler id

query Parameters
wait_saving
integer
Default: 1
Enum: 0 1

whether to wait for raw event saving.

If "0" is specified, the 202 status code will be expected in response to a successful request. This status code is returned after event is validated and added to the buffer. The system does not wait until the event is saved to the database. The event will be stored in the database after the response is sent.

If "1" is specified, the 201 status code will be expected in response to a successful request. This status code is returned only after event is stored in the database.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
Array of objects <= 100 items

list of body & face related detections

source
string (source) <= 128 characters

additional information that user provides with event.

object (input_event_location)

information about place where an event occurred

external_id
string (event_external_id) <= 36 characters
Default: ""

user-defined external ID for the event.

user_data
string (event_user_data) <= 128 characters
Default: ""

user data associated with event

track_id
string (track_id) ^[a-zA-Z0-9_\-]{1,36}$

event track id

object (input_event_face)

face associated with event

Array of objects <= 30 items Nullable

sorted list with match result for the event.

object (input_event_face_attribute) Nullable

user extracted event face attributes

object (input_event_body_attribute) Nullable

user extracted event body attributes

object (event_aggregate_estimations)

aggregated attributes estimated from samples.

tags
Array of strings [ 0 .. 100 ] items

list of tags.

create_time
string <date-time>

time of the event creation.

end_time
string <date-time>

the end time of the event.

Responses

Request samples

Content type
application/json
{
  • "detections": [
    ],
  • "source": "3rd Avenue",
  • "location": {
    },
  • "external_id": "14159261415926",
  • "user_data": "some event",
  • "track_id": "useful_track_id_number_1",
  • "face": {
    },
  • "matches": [
    ],
  • "face_attributes": {
    },
  • "body_attributes": {
    },
  • "aggregate_estimations": {
    },
  • "tags": [
    ],
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "end_time": "2018-08-11T09:11:41.674Z"
}

Response samples

Content type
application/json
{
  • "event_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/events/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get statistics on events

Get event statistics by target(s) with applied filters.

Event fields and/or functions (count, min, etc.) can be set as targets for aggregation of events.

Grouping by frequency or grouping by time intervals is available.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
Array of objects (targets) >= 0 items
Default: [{"column":"event_id","aggregator":"count"}]

You can specify one or several event fields and functions for them for data aggregation.

The table includes event fields and available functions for them:

Column Aggregator
count max min avg group_by
event_id + - - - +
external_id + - - - +
handler_id + - - - +
source + - - - +
top_matching_candidates_label + - - - +
top_similar_object_id + - - - +
top_similar_external_id + - - - +
top_similar_object_similarity + + + + -
create_time + + + - -
end_time + + + - -
face_id + - - - +
gender + + + + +
age + + + + +
emotion + + + + +
mask + + + + +
ethnic_group + + + + +
liveness + + + + +
user_data + - - - +
tags + + + - -
city + - - - +
area + - - - +
district + - - - +
street + - - - +
house_number + - - - +
geo_position + - - - -
track_id + - - - +

Note! There must be at least one function different from group_by in the targets, otherwise an error occurs.

Array of objects (filters) >= 0 items

specifies filters for events.

Operators available for each filter:

Filter Operator
like, nlike in, nin eq, neq gt, gte, lt, lte covered
tags + - - - -
source - + + - -
user_data - + + - -
account_id - + + + -
event_id - + + + -
external_id - + + + -
handler_id - + + + -
top_matching_candidates_label - + + + -
top_similar_object_id - + + + -
top_similar_external_id - + + + -
top_similar_object_similarity - - - + -
face_id - + + + -
gender - + + + -
age - + + + -
emotion - + + + -
mask - + + + -
ethnic_group - + + + -
liveness - + + + -
city - + + - -
area - + + - -
district - + + - -
street - + + - -
house_number - + + - -
geo_position - - - - +
track_id - + + - -
Array of objects (periods) >= 0 items

specifies the period of event creation. All the events created during this period will be included in the statistics.

You can set the start and end of the period or only one of the bounds.

Note! You can specify only one period!

group_by
string (group_by)

enables you to group events by creation time according to one of two ways:

1) Grouping by time intervals - number and dimension

Parameter value Description
1m one minute
2h two hours
7d seven days
5w five weeks
3M three months
10y ten years

2) The frequency grouping - one of the following

Parameter value Description
monthOfYear by month of year
weekOfYear by week of year
dayOfYear by day of year
dayOfMonth by day of month
dayOfWeek by day of week
hourOfDay by hours of day
minuteOfHour by minutes of hour

Responses

Request samples

Content type
application/json
{
  • "targets": [
    ],
  • "filters": [
    ],
  • "period": [
    ],
  • "group_by": "dayOfWeek"
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "stats": [
    ]
}

events statistics options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get events

Get events that satisfy filters.

Default filters for events:

  • create_time__lt - current date and time

  • create_time__gte - current date and time minus month

    Default filters are not used if any of the following parameters are defined:

    • list of event IDs (event_ids)
    • lower event ID boundary (event_id__gte)
    • upper event ID boundary (event_id__lt)
    • lower create time boundary (create_time__gte)
    • upper create time boundary (create_time__lt)

The target parameter determines field that will be shown for each event. If target is not set, the response will contain all the fields.

query Parameters
target
string
Enum: "create_time" "end_time" "event_id" "handler_id" "external_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "body_detections" "tags" "user_data" "location" "mask" "track_id"
Example: target=create_time,event_id,face_detections

Comma-separated list of event fields. If set, each event from result will contain only specified fields, otherwise, events with all fields will be returned.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

end_time__gte
string <date-time> (time)
Example: end_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object end_time.

end_time__lt
string <date-time> (time)
Example: end_time__lt=2018-08-11T09:11:41.674Z

upper bound for object end_time.

sources
string
Example: sources=cam1,cam2

comma-separated list of sources. Each event from result will contain one of the given sources.

cities
string
Example: cities=Moscow,New York

comma-separated list of cities. Each event from result will contain one of the given cities in "location" parameter.

areas
string
Example: areas=CAD,Manhattan

comma-separated list of areas. Each event from result will contain one of the given areas in "location" parameter.

districts
string
Example: districts=Mitino,Midtown

comma-separated list of districts. Each event from result will contain one of the given districts in "location" parameter.

streets
string
Example: streets=Arbat,West 48th street

comma-separated list of streets. Each event from result will contain one of the given streets in "location" parameter.

house_numbers
string
Example: house_numbers=1,220

comma-separated list of house numbers. Each event from result will contain one of the given house numbers in "location" parameter.

origin_longitude
number (longitude) [ -180 .. 180 ]
Example: origin_longitude=36.616

longitude origin in degrees, a part of composite geo position filter.

Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.

Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

NOTE: highly recommended for citywide use only.

origin_latitude
number (latitude) [ -90 .. 90 ]
Example: origin_latitude=55.752

latitude origin in degrees, a part of composite geo position filter.

Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.

Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

NOTE: highly recommended for citywide use only.

longitude_delta
number (longitude_delta) [ 0 .. 90 ]
Default: 0.01
Example: longitude_delta=0.01

longitude delta in degrees, a part of composite geo position filter.

Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.

Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

If both origin_longitude and origin_latitude are set and longitude_delta is not set - the default value is applied.

WARNING: Bounding boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected.

NOTE: highly recommended for citywide use only.

latitude_delta
number (latitude_delta) [ 0 .. 90 ]
Default: 0.01
Example: latitude_delta=0.01

latitude delta in degrees, a part of composite geo position filter.

Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.

Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

If both origin_longitude and origin_latitude are set and latitude_delta is not set - the default value is applied.

WARNING: Bounding boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected.

NOTE: highly recommended for citywide use only.

top_matching_candidates_label
string
Example: top_matching_candidates_label=matching_label

Top matching candidates label. Each event from result will contain the given label.

top_similar_object_ids
Array of strings (external_id)
Example: top_similar_object_ids=14159261415926

comma-separated list of top similar object ids. Each event from result will contain one of the given top similar object ids.

top_similar_external_ids
Array of strings <uuid> (uuid)
Example: top_similar_external_ids=557d54ec-29ad-4f3c-93b4-c9092ef12515

comma-separated list of top similar external ids. Each event from result will contain one of the given top similar external ids.

top_similar_object_similarity__gte
number
Example: top_similar_object_similarity__gte=0.5

top similar object similarity lower included bound.

top_similar_object_similarity__lt
number
Example: top_similar_object_similarity__lt=0.5

top similar object similarity upper excluded bound.

age__lt
integer
Example: age__lt=50

age upper excluded bound.

age__gte
integer
Example: age__gte=50

age lower included bound.

gender
integer
Enum: 0 1
Example: gender=1

Gender. 1 - male, 0 - female.

emotions
string <list of integer (1, 2, 3, 4, 5, 6, 7)>
Example: emotions=1,2,3

comma-separated list of predominant emotions. Each event from result will contain one of the given emotions.

emotions value
anger 1
disgust 2
fear 3
happiness 4
neutral 5
sadness 6
surprise 7
masks
string <list of integer (1, 2, 3)>
Example: masks=1,2,3

comma-separated list of predominant mask states. Each event from result will contain one of the given mask states.

mask state value
missing 1
medical_mask 2
occluded 3
ethnic_groups
string <list of integer (1, 2, 3, 4)>
Example: ethnic_groups=1,2

comma-separated list of dominant ethnic groups. Each event from result will contain one of the given ethnic groups.

ethnicity value
AfricanAmerican 1
Indian 2
Asian 3
Caucasian 4
liveness
string <list of integer (0, 1 ,2)>
Example: liveness=1,2

comma-separated list of dominant liveness. Each event from result will contain one of the given liveness.

liveness value
spoof 0
real 1
unknown 2
face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated face ids.

event_ids
string <list of uuid.>
Example: event_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated event ids.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

event id lower included bound.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc381

event id upper excluded bound.

handler_ids
string <list of uuid.>
Example: handler_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated handler ids.

external_ids
string
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated external ids.

user_data
string
Example: user_data=user_data_text

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

tags
Array of strings (tag) >= 0 items
Example: tags=tag_1,tag_2

comma-separated list of tags. Each event from result will contain all of the given tags. Each tag can be at most 36 characters.

track_ids
string^([a-zA-Z0-9_\-](1, 36))(,[a-zA-Z0-9_\-](1, 3...
Example: track_ids=track_id_number_1,track_id_number_2

comma-separated list of track ids. Each event from result will contain one of the given track ids. Each track id can be at most 36 characters.

order
string
Enum: "asc" "desc"

the sort order. If "desc" is set, the newest events will be shown first. If "asc" is set, the oldest events will be shown first.

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 1000 ]
Default: 10

the number of items on page.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

params = {
    "age__lt": 90,
    "cities": "New York,Moscow",
    "track_ids": "There_and_Back_Again,Around_the_World",
    "emotions": "3,4,5,6,7",
}

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/events"

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

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

events options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get event

Get event by ID.

The target parameter determines field that will be shown for specified event. If target is not set, the response will contain all the fields.

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

event id

query Parameters
target
string
Enum: "create_time" "end_time" "event_id" "handler_id" "external_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "body_detections" "tags" "user_data" "location" "mask" "track_id"
Example: target=create_time,event_id,face_detections

Comma-separated list of event fields. If set, an event from result will contain only specified fields, otherwise, an event with all fields will be returned.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/handlers"
payload = {
    "description": "non_dynamic_handler",
    "policies": {},
    "is_dynamic": False,
}
handlerId = requests.post(url, json=payload, headers=headers).json()["handler_id"]

with open("image.jpg", "rb") as image_file:
    image = image_file.read()

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
    "Luna-Event-Time": "2020-10-10T09:11:41.674Z",
}
url = f"{baseUri}/handlers/{handlerId}/events"

eventId = requests.post(
    url,
    headers=headers,
    data=image,
).json()["events"][0]["event_id"]

# We are waiting for the event to be created
time.sleep(5)

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/events/{eventId}"

response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "create_time": "2020-10-11T09:11:41.674Z",
  • "end_time": "2020-10-11T09:11:41.674Z",
  • "event_id": "bd6df8ea-1df2-449d-b8e3-d1d40b215dc8",
  • "handler_id": "791f002e-919c-459d-b766-cba9f4130853",
  • "face_id": "e88b8804-fedb-4dc3-8a59-171caf416571",
  • "account_id": "a778c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
  • "source": "3rd Avenue",
  • "top_match": {
    },
  • "match_result": [
    ],
  • "face_detections": [
    ],
  • "body_detections": [
    ],
  • "attach_result": [
    ],
  • "gender": 1,
  • "age": 27,
  • "emotion": 5,
  • "mask": 1,
  • "ethnic_group": 3,
  • "tags": [
    ],
  • "user_data": "people are strange",
  • "location": {
    },
  • "track_id": "e3ed4e18-2983-418d-879a-825e4517fc6c"
}

check event existence

Check existence of the event with id=event_id.

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

event id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/handlers"
payload = {
    "description": "non_dynamic_handler",
    "policies": {},
    "is_dynamic": False,
}
handlerId = requests.post(url, json=payload, headers=headers).json()["handler_id"]

# emit event
with open("image.jpg", "rb") as image_file:
    image = image_file.read()

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Content-Type": "image/jpeg",
    "Luna-Event-Time": "2020-10-10T09:11:41.674Z",
}
url = f"{baseUri}/handlers/{handlerId}/events"

eventId = requests.post(
    url,
    headers=headers,
    data=image,
).json()["events"][0]["event_id"]

# We are waiting for the event to be created
time.sleep(5)

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/events/{eventId}"

response = requests.head(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

event options

get options for the resource

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

event id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

task processing

clustering task

Create a new clustering task.

The Filters section enables to specify filters for faces or events clustering. Objects corresponding to all of the filters will be added to the cluster.

Available filters depend on the object type: events or faces.

You can receive a report about the finished clustering task using the reporter task.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

user data provided for the current task

required
object (clustering_task_content)

clustering task content

Responses

Request samples

Content type
application/json
{
  • "description": "clustering faces",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 17
}

clustering options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

reporter task

Create a task report in CSV format.

Now the report is only created for clustering tasks.

The report contains additional information about clustering objects (faces or events). You can specify additional information that will be added to the report. The first and the second columns in the report always correspond to a cluster number and an object ID.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results. The result is returned in ZIP archive, which contains a CSV file. If you set the save_images parameter, then the ZIP archive will also contain a folder with images.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

provided user data for the current task

required
object (ReporterTaskContent)

reporter task content

Responses

Request samples

Content type
application/json
{
  • "description": "report clustering events from cam1",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 17
}

reporter options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

exporter task

Collect event and/or face data and export them from LP to a CSV file. The file rows represent requested objects. Corresponding samples (if they were requested) are also returned.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results. The result is returned in ZIP archive, which contains a CSV file. If you set the save_images parameter, then the ZIP archive will also contain a folder with images.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

task description

required
any

exporter task content

Responses

Request samples

Content type
application/json
{
  • "description": "task description",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 31
}

exporter options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

linker task

Create a new linker task.

The task enables you to attach faces to the specified list according to the filters.

You can use faces or events as objects for the task. When events are used, a new face is created for each of the events.

A list is required for the task processing:

  • If you specified a list, the Tasks service checks its existence and displays an error if the list is not found.
  • If you set new list creation using create_list = 1, a new list is created.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

user data provided for the current task

required
object (linker_task_content)

linker task content

Responses

Request samples

Content type
application/json
{
  • "description": "linker task one",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 29
}

linker options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

garbage collection task

Create a new garbage collection task.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
One of
description
string

user data provided for the current task.

required
object (GcEventsTaskContent)

garbage collecting task content to remove events

Responses

Request samples

Content type
application/json
{
  • "description": "gc task one",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 25
}

gc options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

cross-matching task

Create a new cross-matching task.

The cross-matching task enables you to compare references (faces, attributes or events) with candidates (faces, attributes or events) according to the specified filters.

All the references are matched with all the candidates.

You can limit the number of candidates returned in matching results and set the minimum acceptable similarity threshold.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

user data provided for the current task

required
object (CrossMatchTaskContent)

cross match task content

Responses

Request samples

Content type
application/json
{
  • "description": "matching visitors with the list of VIP customers",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 15
}

cross match options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

ROC-curve calculating task

create a ROC-curve calculating task.

ROC (or Receiver Operating Characteristic) is a performance measurement for the classification problem at various threshold settings. The ROC-curve is plotted with TPR (True Positive Rate) against the FPR (False Positive Rate).

TPR is a true positive match pair count divided by a count of total expected positive match pairs, and FPR is a false positive match pair count divided by a count of total expected negative match pairs. Each point (FPR, TPR) of the ROC-cure corresponds to a certain similarity threshold.

The model performance is determined by looking at the area under the ROC-curve (or AUC), the ROC-curve and the secondary main diagonal intersection point, where type I and type II error rates are equal. The model performance is also determined by getting into the top-N probability, i.e. probability of getting a positive match pair into the top-N for any match result group sorted by similarity.

Use the GET request on resource /6/tasks/{task_id}/result to receive the task results.

If there are no results of the created task and error "Object not found" is returned, use the GET request on resource /6/tasks/errors/{error_id} to receive the task errors.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

user data provided for the current task.

required
object (roc_task_content)

ROC-curve calculating task content.

Responses

Request samples

Content type
application/json
{
  • "description": "matching famous people with customers",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 14
}

roc options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

estimator task

create new estimator task.

Task allows to process images using established policies. Policies can be specified in the request or use saved ones by passing the handler ID. Currently, it is possible to send images only as an zip-archive, indicating a link to it.

WARNING: Check handler storage_policy before a task start, notification_policy and event_policy enable by default.

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

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

Content-Type
string
Value: "application/json"

content type is application/json.

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Request Body schema: application/json
description
string

provided user data for current task.

required
object (estimator_task_content)

estimator task content

Responses

Request samples

Content type
application/json
Example
{
  • "description": "estimator task with zip archive",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "task_id": 123
}

estimator options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

task info

get tasks

Get tasks according to the filters.

query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

end_time__lt
string <date-time> (time)
Example: end_time__lt=2018-08-11T09:11:41.674Z

upper bound for object end_time.

end_time__gte
string <date-time> (time)
Example: end_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object end_time.

task_ids
string <comma-separate task ids> (taskIds)
Example: task_ids=1,2,3

comma-separated task ids

task_type
integer (task_type)
Enum: 0 1 2 3 4 5 6 7 8 9
Example: task_type=1

task type

task type value
unknown 0
linker 1
clusterization 2
report 3
garbage collect 4
additional extract 5
cross match 6
roc-curve calculation 7
export objects 8
estimate data 9
task_status
integer (taskStatus)
Enum: 0 1 2 3 4 5
Example: task_status=1

task status

task status value
pending 0
in progress 1
cancelled 2
failed 3
collect results 4
done 5
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

params = {
    "task_id": taskId,
    "task_type": 4,
    "task_status": 5,
    "create_time__gte": "2018-08-11T09:11:41.674Z",
    "page": 1,
}

url = f"{baseUri}/tasks"
response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

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

tasks options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get tasks count

Count tasks according to the filters.

query Parameters
create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

end_time__lt
string <date-time> (time)
Example: end_time__lt=2018-08-11T09:11:41.674Z

upper bound for object end_time.

end_time__gte
string <date-time> (time)
Example: end_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object end_time.

task_ids
string <comma-separate task ids> (taskIds)
Example: task_ids=1,2,3

comma-separated task ids

task_type
integer (task_type)
Enum: 0 1 2 3 4 5 6 7 8 9
Example: task_type=1

task type

task type value
unknown 0
linker 1
clusterization 2
report 3
garbage collect 4
additional extract 5
cross match 6
roc-curve calculation 7
export objects 8
estimate data 9
task_status
integer (taskStatus)
Enum: 0 1 2 3 4 5
Example: task_status=1

task status

task status value
pending 0
in progress 1
cancelled 2
failed 3
collect results 4
done 5
header Parameters
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

params = {
    "task_id": taskId,
    "task_type": 4,
    "task_status": 5,
    "create_time__gte": "2018-08-11T09:11:41.674Z",
    "page": 1,
}

url = f"{baseUri}/tasks/count"
response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "count": 13
}

tasks count options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get task

Get task by ID.

path Parameters
task_id
required
integer >= 1

task id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "task_id": 13,
  • "account_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "end_time": "2018-08-11T10:11:41.674Z",
  • "last_update_time": "2018-08-11T10:11:41.674Z",
  • "task_type": 1,
  • "task_status": 5,
  • "result_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "count_task_parts_done": 10,
  • "count_task_parts_all": 10,
  • "content": {
    },
  • "description": "task description"
}

cancel task

Cancel task by ID.

path Parameters
task_id
required
integer >= 1

task id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}"
response = requests.patch(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

delete task

Delete a task and the task results by the task ID.

path Parameters
task_id
required
integer >= 1

task id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}"
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
Example
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

task options

get options for the resource

path Parameters
task_id
required
integer >= 1

task id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get task result

Get task result by the task ID.

In addition to the result of the task, the occurred errors can be returned in the response.

path Parameters
task_id
required
integer >= 1

task id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}/result"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
Example
{
  • "result": [
    ],
  • "errors": [ ]
}

task result options

get options for the resource

path Parameters
task_id
required
integer >= 1

task id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get subtasks

Get subtasks of a task by ID.

path Parameters
task_id
required
integer >= 1

task id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/gc"
payload = {"content": {"target": "events"}}
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}/subtasks"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

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

subtasks options

get options for the resource

path Parameters
task_id
required
integer >= 1

task id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

task errors

get task errors

Get errors of a task by the task ID.

path Parameters
task_id
required
integer >= 1

task 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
Luna-Request-Id
string^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time
from uuid import uuid4

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

payload = {
    "description": "matching famous people with customers",
    "content": {
        "markup": [
            {"face_id": str(uuid4()), "label": 1},
            {"face_id": str(uuid4()), "label": 2},
        ],
    },
}

url = f"{baseUri}/tasks/roc"
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}

url = f"{baseUri}/tasks/{taskId}/errors"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

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

task errors options

get options for the resource

path Parameters
task_id
required
integer >= 1

task id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get errors

Get errors according to the filters.

query Parameters
page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

task_ids
string <comma-separate task ids> (taskIds)
Example: task_ids=1,2,3

comma-separated task ids

error_code
integer (error_code)

error code

error_ids
string <comma-separate task ids> (errorIds) non-empty
Example: error_ids=4,5,6

comma-separated error ids

error_time__lt
string <date-time> (time)
Example: error_time__lt=2018-08-11T09:11:41.674Z

upper bound for object error_time.

error_time__gte
string <date-time> (time)
Example: error_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object error_time.

task_type
integer (task_type)
Enum: 0 1 2 3 4 5 6 7 8 9
Example: task_type=1

task type

task type value
unknown 0
linker 1
clusterization 2
report 3
garbage collect 4
additional extract 5
cross match 6
roc-curve calculation 7
export objects 8
estimate data 9
status_code
integer (status_code) [ 400 .. 599 ]
Example: status_code=500

http status code

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time
from uuid import uuid4

baseUri = "http://127.0.0.1:5000/6"

# create bad task
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "description": "matching famous people with customers",
    "content": {
        "markup": [
            {"face_id": str(uuid4()), "label": 1},
            {"face_id": str(uuid4()), "label": 2},
        ],
    },
}
url = f"{baseUri}/tasks/roc"
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

# get tasks error id list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/{taskId}/errors"
response = requests.get(url, headers=headers)
errorIds = [
    str(error["error_id"]) for error in response.json()["errors"]
]

# get error according to the filters
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "errors": [
        {
            "error_id": ",".join(errorIds),
            "task_id": taskId,
            "error_time__gte": "2018-08-11T09:11:41.674Z",
        }
    ]
}

url = f"{baseUri}/tasks/errors"
response = requests.get(url, headers=headers, json=payload)

print(response.status_code)
print(response.json())

Response samples

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

errors options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get errors count

Count errors according to the filters.

query Parameters
error_time__lt
string <date-time> (time)
Example: error_time__lt=2018-08-11T09:11:41.674Z

upper bound for object error_time.

error_time__gte
string <date-time> (time)
Example: error_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object error_time.

task_type
integer (task_type)
Enum: 0 1 2 3 4 5 6 7 8 9
Example: task_type=1

task type

task type value
unknown 0
linker 1
clusterization 2
report 3
garbage collect 4
additional extract 5
cross match 6
roc-curve calculation 7
export objects 8
estimate data 9
status_code
integer (status_code) [ 400 .. 599 ]
Example: status_code=500

http status code

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time
from uuid import uuid4

baseUri = "http://127.0.0.1:5000/6"

# create bad task
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "description": "matching famous people with customers",
    "content": {
        "markup": [
            {"face_id": str(uuid4()), "label": 1},
            {"face_id": str(uuid4()), "label": 2},
        ],
    },
}
url = f"{baseUri}/tasks/roc"
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

# get tasks error id list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/{taskId}/errors"
response = requests.get(url, headers=headers)
errorIds = [
    str(error["error_id"]) for error in response.json()["errors"]
]

# get error count
headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "errors": [
        {
            "error_id": ",".join(errorIds),
            "task_id": taskId,
            "error_time__gte": "2018-08-11T09:11:41.674Z",
        }
    ]
}

url = f"{baseUri}/tasks/errors/count"
response = requests.get(url, headers=headers, json=payload)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "count": 18
}

task errors count options

get options for the resource

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get error

Get error by ID.

path Parameters
error_id
required
integer >= 1

error id

query Parameters
error_id
integer (errorId)
Example: error_id=10

error id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests
import time
from uuid import uuid4

baseUri = "http://127.0.0.1:5000/6"

# create bad task
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
payload = {
    "description": "matching famous people with customers",
    "content": {
        "markup": [
            {"face_id": str(uuid4()), "label": 1},
            {"face_id": str(uuid4()), "label": 2},
        ],
    },
}
url = f"{baseUri}/tasks/roc"
taskId = requests.post(url, headers=headers, json=payload).json()["task_id"]

# wait for tasks to complete
time.sleep(5)

# get tasks error id list
headers = {
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/tasks/{taskId}/errors"
response = requests.get(url, headers=headers)
errorId = [
    str(error["error_id"]) for error in response.json()["errors"]
][0]

url = f"{baseUri}/tasks/errors/{errorId}"
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "error_id": 5808750,
  • "task_id": 14980,
  • "subtask_id": 69825,
  • "error_code": 28010,
  • "description": "Objects not found",
  • "detail": "Objects for clustering not found (empty set)",
  • "additional_info": null,
  • "error_time": "2019-04-29T10:53:42.417396+03:00"
}

error options

get options for the resource

path Parameters
error_id
required
integer >= 1

error id

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

verifiers

create verifier

Create a new verifier.

The verifier determinates a list of rules for processing and verification of input images.

You can set:

  • verification_threshold
  • detect_policy
  • extract_policy
  • storage_policy for attributes and face samples.

The created handler can be used in "raw verification" and "perform verification" requests.

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

verifier user description.

object

Responses

Request samples

Content type
application/json
{
  • "description": "strict verifier",
  • "policies": {
    }
}

Response samples

Content type
application/json
{
  • "verifier_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/6/verifiers/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get verifiers

Get verifiers by filters

query Parameters
description
string

records with descriptions similar to this parameter will be processed.

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/verifiers"

payload = {
    "description": "new verifier",
    "policies": {
        "verification_threshold": 0.5,
        "detect_policy": {
            "estimate_mask": 1
        },
        "extract_policy": {
            "extract_basic_attributes": 1
        },
        "storage_policy": {
            "attribute_policy": {
                "store_attribute": 1
            },
            "face_sample_policy": {
                "store_sample": 1
            }
        }
    }
}

# create verifier
requests.post(url, json=payload, headers=headers)

# get verifiers
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

raw verification

This request performs verification of input descriptors.

"Similarity" and "verification status" are returned for each candidate.

"Verification status" is "True" if the received similarity is greater than the verification_threshold (specified in the verifier handler). Hence, the reference and the candidate are considered the same person.

You should specify descriptors as references and candidates for this request.

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

verifier id

header Parameters
Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

Format of a request body data

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

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

Request Body schema:
required
Array of xpk_file_entity_base64 (object) or sdk_descriptor_entity_base64 (object) or raw_descriptor_entity_base64 (object) non-empty

reference list for verification

required
Array of xpk_file_entity_base64 (object) or sdk_descriptor_entity_base64 (object) or raw_descriptor_entity_base64 (object) non-empty

candidates for verification

Responses

Request samples

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

Response samples

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

perform verification

Verify given images and/or descriptors against specified objects set: faces IDs, events IDs, external IDs.

"Similarity" and "verification status" are returned for each candidate.

"Verification status" is "True" if the received similarity is greater than the verification_threshold (specified in the verifier handler). Hence, the reference and the candidate are considered the same person.

The input images are processed according to the specified policies and the received information is returned in the response.

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

verifier id

query Parameters
face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated face ids.

event_ids
string <list of uuid.>
Example: event_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated event ids.

attribute_ids
string <list of uuid>
Example: attribute_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated attribute ids.

external_ids
string
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated external ids.

use_exif_info
integer
Default: 1
Enum: 0 1
Example: use_exif_info=1

whether to try to auto orient image based on EXIF data

The processed image should have EXIF data, otherwise auto orientation will not be performed.

Has no effect with tiff images (they're always auto oriented).

Ignored with warped images (see warped_image or image_type parameter).

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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" "application/x-sdk-descriptor" "application/x-sdk-descriptor-base64" "application/x-vl-xpk" "application/x-vl-xpk-base64"
Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

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

count verifiers

Count verifiers that satisfy the filters

query Parameters
description
string

records with descriptions similar to this parameter will be processed.

header Parameters
Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

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

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

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/verifiers"

payload = {
    "description": "new verifier",
    "policies": {
        "verification_threshold": 0.5,
        "detect_policy": {
            "estimate_mask": 1
        },
        "extract_policy": {
            "extract_basic_attributes": 1
        },
        "storage_policy": {
            "attribute_policy": {
                "store_attribute": 1
            },
            "face_sample_policy": {
                "store_sample": 1
            }
        }
    }
}

# create verifier
requests.post(url, json=payload, headers=headers)

url = f"{url}/count"

# get verifiers count
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "verifiers_count": 4
}

get verifier

Get verifier by id.

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

verifier id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/verifiers"

payload = {
    "description": "new verifier",
    "policies": {
        "verification_threshold": 0.5,
        "detect_policy": {
            "estimate_mask": 1
        },
        "extract_policy": {
            "extract_basic_attributes": 1
        },
        "storage_policy": {
            "attribute_policy": {
                "store_attribute": 1
            },
            "face_sample_policy": {
                "store_sample": 1
            }
        }
    }
}

# create verifier
response = requests.post(url, json=payload, headers=headers)
verifierId = response.json()["verifier_id"]

url = f"{url}/{verifierId}"

# get verifier
response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Response samples

Content type
application/json
{
  • "verifier_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "account_id": "0468ca85-f6ca-4841-b30c-5ccc26b6f397",
  • "description": "simple verifier",
  • "policies": {
    },
  • "create_time": "2019-08-24T14:15:22Z",
  • "last_update_time": "2019-08-24T14:15:22Z",
  • "version": 111
}

replace verifier

Update the verifier. You can not update a part of verifier, so you should specify all the fields for your handler.

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

verifier id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Content-Type
string
Value: "application/json"

content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

verifier user description.

object

Responses

Request samples

Content type
application/json
{
  • "description": "strict verifier",
  • "policies": {
    }
}

Response samples

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

check verifier

Check the verifier existense.

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

verifier id

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/verifiers"

payload = {
    "description": "new verifier",
    "policies": {
        "verification_threshold": 0.5,
        "detect_policy": {
            "estimate_mask": 1
        },
        "extract_policy": {
            "extract_basic_attributes": 1
        },
        "storage_policy": {
            "attribute_policy": {
                "store_attribute": 1
            },
            "face_sample_policy": {
                "store_sample": 1
            }
        }
    }
}

# create verifier
response = requests.post(url, json=payload, headers=headers)
verifierId = response.json()["verifier_id"]

url = f"{url}/{verifierId}"

# check verifier
response = requests.head(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

remove verifier

Remove verifier by id.

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

verifier id

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

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

Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {"Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"}

url = f"{baseUri}/verifiers"

payload = {
    "description": "new verifier",
    "policies": {
        "verification_threshold": 0.5,
        "detect_policy": {
            "estimate_mask": 1
        },
        "extract_policy": {
            "extract_basic_attributes": 1
        },
        "storage_policy": {
            "attribute_policy": {
                "store_attribute": 1
            },
            "face_sample_policy": {
                "store_sample": 1
            }
        }
    }
}

# create verifier
response = requests.post(url, json=payload, headers=headers)
verifierId = response.json()["verifier_id"]

url = f"{url}/{verifierId}"

# delete verifier
response = requests.delete(url, headers=headers)

print(response.status_code)

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

ws

ws handshake

ws handshake

Attention!

Subscription to events occurs via WebSocket. Messages sent by ws you can view in callback section. Connection supports autoping.

query Parameters
sources
string
Example: sources=cam1,cam2

comma-separated list of sources. Each event from result will contain one of the given sources.

matching_candidates_labels
string
Example: matching_candidates_labels=matching_label_1,matching_label_2

comma-separated list of matching candidates label. Each event from result will contain one or more given labels.

object_similarity__gte
number
Example: object_similarity__gte=0.5

Object similarity lower included bound (boundary for top matching candidate).

object_similarity__lt
number
Example: object_similarity__lt=0.5

Object similarity upper excluded bound (boundary for top matching candidate).

age__lt
integer
Example: age__lt=50

age upper excluded bound.

age__gte
integer
Example: age__gte=50

age lower included bound.

gender
integer
Enum: 0 1
Example: gender=1

Gender. 1 - male, 0 - female.

ethnic_groups
string <list of integer (1, 2, 3, 4)>
Example: ethnic_groups=1,2

comma-separated list of dominant ethnic groups. Each event from result will contain one of the given ethnic groups.

ethnicity value
AfricanAmerican 1
Indian 2
Asian 3
Caucasian 4
liveness
string <list of integer (0, 1 ,2)>
Example: liveness=1,2

comma-separated list of dominant liveness. Each event from result will contain one of the given liveness.

liveness value
spoof 0
real 1
unknown 2
tags
Array of strings (tag) >= 0 items
Example: tags=tag_1,tag_2

comma-separated list of tags. Each event from result will contain all of the given tags. Each tag can be at most 36 characters.

cities
string
Example: cities=Moscow,New York

comma-separated list of cities. Each event from result will contain one of the given cities in "location" parameter.

areas
string
Example: areas=CAD,Manhattan

comma-separated list of areas. Each event from result will contain one of the given areas in "location" parameter.

districts
string
Example: districts=Mitino,Midtown

comma-separated list of districts. Each event from result will contain one of the given districts in "location" parameter.

streets
string
Example: streets=Arbat,West 48th street

comma-separated list of streets. Each event from result will contain one of the given streets in "location" parameter.

house_numbers
string
Example: house_numbers=1,220

comma-separated list of house numbers. Each event from result will contain one of the given house numbers in "location" parameter.

handler_ids
string <list of uuid.>
Example: handler_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc381

list of comma-separated handler ids.

masks
string <list of integer (1, 2, 3)>
Example: masks=1,2,3

comma-separated list of predominant mask states. Each event from result will contain one of the given mask states.

mask state value
missing 1
medical_mask 2
occluded 3
emotions
string <list of integer (1, 2, 3, 4, 5, 6, 7)>
Example: emotions=1,2,3

comma-separated list of predominant emotions. Each event from result will contain one of the given emotions.

emotions value
anger 1
disgust 2
fear 3
happiness 4
neutral 5
sadness 6
surprise 7
header Parameters
Luna-Account-Id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests, request to sdk resource and getting events statistics requests).

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

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

Responses

Request samples

from luna3.lunavl.httpclient import LunaHttpClient

EXPECTED_EVENT_COUNT = 1

client = LunaHttpClient(origin='http://127.0.0.1:5000', api=6, accountId="8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a")
with client.wsConnect() as ws:
    for _ in range(EXPECTED_EVENT_COUNT):
        WS_RESP = ws.recv()
        print(WS_RESP)

Response samples

Content type
application/json
{
  • "event": {
    },
  • "handler_id": "88c5dd7e-693b-4386-92bc-0c31a150a7d0",
  • "event-create-time": "2021-06-18T02:44:58.653485+03:00",
  • "event-end-time": "2021-06-18T02:44:58.653485+03:00",
  • "Luna-Request-id": "1623984298,375c6d96-09c7-4db3-91cc-f13e66288aa9"
}

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 version. See "Administrator’s manual" for details.

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

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

whether to aggregate liveness estimations.

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

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

Luna-Account-Id
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

account ID.

An account is a limitation for all the user actions (matching, removing, updating and other) on data which does not have corresponding account ID. For example: it is impossible to attach a face with one account ID to a list with another account ID.

User can make a limited set of requests without this header (requests with methods GET, HEAD, OPTIONS, match requests and getting events statistics requests).

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": {
    }
}

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 is text/html

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

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

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

acceptable type of receiving data

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

get development manual

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

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

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

Responses

Response samples

Content type
application/json
{
  • "error_code": 37003,
  • "desc": "Payload too large",
  • "detail": "Request payload is too large"
}

config

get service configuration

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

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

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

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

acceptable type of receiving data

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

headers = {
    "Luna-Request-Id": "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    "Luna-Account-Id": "8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
}
url = f"{baseUri}/config"

response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

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

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

Responses

Request samples

# This example is written using requests library

import requests

baseUri = "http://127.0.0.1:5000/6"

# make request
url = f"{baseUri}/healthcheck"
response = requests.get(url, params={"include_luna_services": 1})

print(response.status_code)
print(response.json())

Response samples

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

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^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

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

Responses

Request samples

# This example is written using requests library

import requests

# make request
url = f"http://127.0.0.1:5000/healthcheck"
response = requests.get(url, params={"include_luna_services": 1})

print(response.status_code)
print(response.json())

Response samples

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