API docs by Redocly

Luna-Handlers (v.3.5.0)

Download OpenAPI specification:Download

VisionLabs Luna Handlers API

version

get version

Get version of service.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

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

samples

detect faces

Detect faces in input images.

Notes for incoming data:

  • face or body bounding boxes passed with face or body wapred image will be ignored.
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 best face detection from the image

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

Whether to estimate head pose on the image.

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

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

Whether to estimate emotions on the image.

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

Whether to estimate mask on the image.

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

Whether to detect basic 68-point facial landmarks on the image.

Not supported with warped images (see warped_image or image_type 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.

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

Whether to estimate eye gaze on the image.

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 on the image.

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

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

Whether to estimate mouth attributes on the image.

pitch_threshold
integer (pitch_threshold) [ 0 .. 180 ]

Maximum deviation pitch angle from 0.

roll_threshold
integer (roll_threshold) [ 0 .. 180 ]

Maximum deviation roll angle from 0.

yaw_threshold
integer (yaw_threshold) [ 0 .. 180 ]

Maximum deviation yaw angle from 0.

warped_image
integer (warped_image) [ 0 .. 1 ]

Whether input image is a warped or arbitrary image.

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

Whether to try to auto orient image based on exif data

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

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

estimate_face_quality
integer
Default: 0
Enum: 0 1

Whether to estimate face quality.

It enables you to perform various face quality checks by thresholds which similar to ISO standard. For more information on the requirements for face attributes in the image, see ISO/IEC 19794-5 Clauses 7-10.

⚠ ISO licensing feature is required to be enabled to perform face quality estimation.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

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

Responses

Request samples

Content type
No sample

Response samples

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

attributes

extract attributes

Extract attributes from samples.

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

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

extract_descriptor
integer (extract_descriptor)
Default: 1
Enum: 0 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)
Enum: 0 1

Whether to aggregate face descriptor(s).

If true, all extracted attributes will be aggregated and stored as a single attribute. Otherwise, all attributes will be stored for each sample.

ttl
integer [ 1 .. 86400 ]
Default: 300

Lifetime for temporary attribute (seconds).

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

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

Responses

Request samples

Content type
application/json
[
  • "557d54ec-29ad-4f3c-93b4-c9092ef12515"
]

Response samples

Content type
application/json
[
  • {
    }
]

upgrade attribute

Append a descriptor of non-default version and/or replace basic attributes from samples.

header Parameters
Luna-Account-Id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

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

Face ID.

required
object (face_upgrade_data)

Face samples and its upgrade rules.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "face_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "url": "http://127.0.0.1:5030/3/faces/24d405ce-bc56-4bf7-98e1-bdc962b4cf34/attributes",
  • "face_attributes": {
    }
}

handlers

create handler

Create a new handler. The handler determinates a list of rules for processing of input images. You can set parameters for detecting faces and/or human bodies and extracting attributes. You can set rules for matching attributes and creating faces from them.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

User description.

object (Policies)

Set of rules, that determines input images processing

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

Whether to get only non-dynamic (0), dynamic (1) or lambda (2) handlers.

If type is non-dynamic:

  • Handler will use policies what assigned to it.

If type is dynamic:

  • Handler will use given policies for each event generation request.

If type is lambda:

  • All requests will be sent to lambda handler using lambda_id.
  • The format of the request and response body may not match what is specified for canonical handlers.
  • Logic of the request behavior completely depends on the lambda, written by the user.
  • For a description, see documentation of the lambda, for example via luna-lambda service.
lambda_id
string <uuid> (lambda_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Id of lambda handler. Lambda handler it is user customizable handler.

Responses

Request samples

Content type
application/json
{
  • "description": "second avenue",
  • "policies": {
    },
  • "handler_type": 0,
  • "lambda_id": "string"
}

Response samples

Content type
application/json
{
  • "handler_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/1/handlers/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get handlers

Get handlers by filters.

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

Account ID.

handler_type
integer
Enum: 0 1 2

Whether to get only non-dynamic (0), dynamic (1) or lambda (2) handlers.

If type is non-dynamic:

  • Handler will use policies what assigned to it.

If type is dynamic:

  • Handler will use given policies for each event generation request.

If type is lambda:

  • All requests will be sent to lambda handler using lambda_id.
  • The format of the request and response body may not match what is specified for canonical handlers.
  • Logic of the request behavior completely depends on the lambda, written by the user.
  • For a description, see documentation of the lambda, for example via luna-lambda service.
page
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 1000 ]
Default: 10

Number of items on page.

description
string

Find all handlers with description similar to this parameter.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get handler count

Get handler count.

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

Account ID.

description
string

Find all handlers with description similar to this parameter.

handler_type
integer
Enum: 0 1 2

Whether to get only non-dynamic (0), dynamic (1) or lambda (2) handlers.

If type is non-dynamic:

  • Handler will use policies what assigned to it.

If type is dynamic:

  • Handler will use given policies for each event generation request.

If type is lambda:

  • All requests will be sent to lambda handler using lambda_id.
  • The format of the request and response body may not match what is specified for canonical handlers.
  • Logic of the request behavior completely depends on the lambda, written by the user.
  • For a description, see documentation of the lambda, for example via luna-lambda service.
header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "handlers_count": 100
}

validate handler policies

Validate handler policies before using them to create or update a handler.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

Request Body schema: application/json
required
object (Policies)

Set of rules, that determines input images processing

Responses

Request samples

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

Response samples

Content type
application/json
Example
{}

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.

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "handler_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "account_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "description": "string",
  • "policies": {
    },
  • "create_time": "2019-08-24T14:15:22Z",
  • "last_update_time": "2019-08-24T14:15:22Z",
  • "handler_type": 0,
  • "lambda_id": "string"
}

Replace handler

Replace the handler. You can not update a part of 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-Account-Id
required
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

Request Body schema: application/json
description
string <= 128 characters

User description.

object (Policies)

Set of rules, that determines input images processing

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

Whether to get only non-dynamic (0), dynamic (1) or lambda (2) handlers.

If type is non-dynamic:

  • Handler will use policies what assigned to it.

If type is dynamic:

  • Handler will use given policies for each event generation request.

If type is lambda:

  • All requests will be sent to lambda handler using lambda_id.
  • The format of the request and response body may not match what is specified for canonical handlers.
  • Logic of the request behavior completely depends on the lambda, written by the user.
  • For a description, see documentation of the lambda, for example via luna-lambda service.
lambda_id
string <uuid> (lambda_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Id of lambda handler. Lambda handler it is user customizable handler.

Responses

Request samples

Content type
application/json
{
  • "description": "second avenue",
  • "policies": {
    },
  • "handler_type": 0,
  • "lambda_id": "string"
}

Response samples

Content type
application/json
Example
{}

check to exist a handler

Check a handler with id=handler_id existence.

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

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.

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

events

generate events

Generate events from images and/or raw descriptor data. If luna-events support is disabled on server, events will not be saved. Do not forget to send policies for a dynamic handler along with emitting events.

Notes for incoming data:

  • set the image detection time, if necessary, otherwise it will be equal to the request time.
  • face or body bounding boxes passed with face or body wapred image will presented as sample detection rect in generated event.
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

Event city.

area
string (location_str) <= 36 characters
Example: area=central park

Event area.

district
string (location_str) <= 36 characters
Example: district=mitino

Event district.

street
string (location_str) <= 36 characters
Example: street=arbat

Event street.

house_number
string (location_str) <= 36 characters
Example: house_number=1/2str3

Event house number.

longitude
number [ -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 [ -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.

track_id
string^[a-zA-Z0-9_\-](1, 36)$
Example: track_id=useful_track_id_number_1

Event track ID.

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

Whether to try to auto orient image based on exif data

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

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

external_id
string (event_external_id) <= 36 characters
Default: ""
Example: external_id=b668c4a5-2191-some-important-words

External ID for created faces.

user_data
string (event_user_data) <= 128 characters
Default: ""
Example: user_data=some data

User data for created faces.

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

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

aggregate_attributes
integer (aggregate_attributes)
Enum: 0 1

Whether to aggregate face descriptor(s).

If true, all extracted attributes will be aggregated and stored as a single attribute. Otherwise, all attributes will be stored for each sample.

source
string (source) <= 128 characters
Example: source=3rd Avenue

Additional information, provided by user with event.

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

Stream id.

no_cache
integer
Default: 0
Enum: 0 1

Flag to disable handler caching.

tags
Array of strings (tag) >= 0 items [ items <= 36 characters ]
Example: tags=tag_1,tag_2

A comma-separated list of tags. Each event from result will contain all of the given tags. Each tag can be at most 36 characters.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Luna-Event-Time
string <date-time> (time)
Examples:
  • 2018-12-16T15:29:59.300275+03:00 - time with timezone
  • 2018-12-16T15:29:59.300275Z - utc time

User defined event time. All events will be saved with this time as "create_time". Format of time is rfc3339. All other format is ignored.

Luna-Event-End-Time
string <date-time> (time)
Examples:
  • 2018-12-16T15:29:59.300275+03:00 - time with timezone
  • 2018-12-16T15:29:59.300275Z - utc time

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-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
{
  • "events": [
    ],
  • "images": [],
  • "filtered_detections": {
    }
}

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 lambdas. Therefore these events are the same events except that the 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
no_cache
integer
Default: 0
Enum: 0 1

Flag to disable handler caching.

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 are validated and added to the buffer. The system does not wait until the event are 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 are stored in the database.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

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

Some additional information that user provided with event.

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

Stream ID.

object (input_location)

Information about a place where event is incidented.

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

Event external ID.

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

Event user data.

track_id
string or null (track_id) ^[a-zA-Z0-9_\-]{1,36}$

Event track ID.

object (event_meta_common)

User defined metadata (json object). Size shouldn't exceed 2MB.

object (input_event_face)

Face structure of input event.

Array of match_candidates_faces (object) or match_candidates_events (object) <= 30 items

Sorted list with match result for the event.

object or null (input_event_face_attribute)

User extracted event face attributes.

object or null (input_event_body_attribute)

User extracted event body attributes.

object (EventAggregateEstimations_masks_occlusion_not_required)

Aggregated attributes estimated from samples.

tags
Array of strings <= 100 items [ items <= 36 characters ]

List of tags.

create_time
string <date-time>

Time in format RFC 3339.

end_time
string <date-time>

Time in format RFC 3339.

Responses

Request samples

Content type
application/json
{
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "end_time": "2018-08-11T10:10:40.555Z",
  • "face_attributes": {
    },
  • "body_attributes": {
    },
  • "source": "3rd Avenue",
  • "stream_id": "a3e8716f-70dc-42ad-8428-7a552e800a37",
  • "tags": [
    ],
  • "external_id": "b668c4a5-2191-some-important-words",
  • "user_data": "string",
  • "meta": {
    },
  • "face": {
    },
  • "matches": [
    ],
  • "location": {
    },
  • "detections": [
    ],
  • "track_id": "useful_track_id_number_1",
  • "aggregate_estimations": {
    }
}

Response samples

Content type
application/json
{}

generate stream events (beta)

Generate stream events from images. If luna-events support is disabled on server, events will not be saved. Do not forget to send policies for a dynamic handler along with emitting events.

Notes for incoming data:

  • set the image detection time, if necessary, otherwise it will be equal to the request time.
  • face or body bounding boxes passed with face or body wapred image will presented as sample detection rect in generated event.
  • if no image specified as event source, the only specified metadata and detections will be processed.
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
no_cache
integer
Default: 0
Enum: 0 1

Flag to disable handler caching.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/msgpack"

Format of a request body data.

Request Body schema: application/msgpack
aggregate_attributes
required
integer (aggregate_attributes)

Whether to aggregate attribute(s).

If true, all extracted attributes will be aggregated and stored as a single attribute. Otherwise, all attributes will be stored for each sample.

required
Array of any (event_sources_non_aggregated) non-empty
use_exif_info
integer (use_exif_info)
Default: 1
Enum: 0 1

Whether to try to auto orient image based on exif data

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

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

Responses

Response samples

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

verifiers

create verifier

Create a new verifier. The verifier determinates a list of rules for processing & verification of input images. You can set parameters for detecting faces and extracting attributes.

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

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

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": "/1/verifiers/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get verifiers

Get verifiers by filters.

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

Account ID.

description
string

Verifier description - verifiers with description similar to this parameter will be processed.

page
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 1000 ]
Default: 10

Number of items on page.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

count verifiers

Count verifiers that satisfy the filters.

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

Account ID.

description
string

Verifier description - verifiers with description similar to this parameter will be processed.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "verifiers_count": 100
}

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.

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "verifier_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "account_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "description": "string",
  • "policies": {
    },
  • "create_time": "2019-08-24T14:15:22Z",
  • "last_update_time": "2019-08-24T14:15:22Z",
  • "version": 111
}

replace verifier

Replace the verifier. You can not update a part of verifier.

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> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Luna account Id. Designed to identify the created object.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

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

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

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.

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

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

raw verification

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

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

Account ID.

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

Account ID.

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

Format of a request body data.

Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with 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.

Notes for incoming data:

  • face or body bounding boxes passed with face or body wapred image will be ignored.
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
account_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

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

List of face IDs

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

List of comma-separated event IDs.

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

List of comma-separated attribute IDs.

external_ids
string
Example: external_ids=abcd_1234,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated external IDs.

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

Whether to try to auto orient image based on exif data

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

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

image_type
integer
Default: 0
Enum: 0 1

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

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "image/jpeg" "image/png" "image/bmp" "image/x-portable-pixmap" "image/tiff" "multipart/form-data" "application/json" "image/x-jpeg-base64" "image/x-png-base64" "image/x-bmp-base64" "image/x-tiff-base64" "image/x-portable-pixmap-base64" "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": [
    ]
}

documents

get openapi documentation

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

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with 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
{}

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 <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

config

get service configuration

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

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

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

Acceptable type of receiving data.

Responses

Response samples

Content type
{
  • "INFLUX_MONITORING": {
    }
}

plugins

get list of plugins

Get list of service plugins

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

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

metrics

get service requests statistics

Get statistics of success and failed requests to the service in prometheus format.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
text/plain
# HELP request_count_total Counter of requests
# TYPE request_count_total counter
request_count_total{path="GET:/healthcheck",status_code="200"} 1.0

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 <timestamp,uuid> ^[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 that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

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