OpenAPI Documentation¶
You can find the OpenAPI specification with requests examples for the Backport 3 service in the html document.
openapi: 3.0.0
info:
version: 'v.0.3.39'
title: 'LUNA Backport 3 API'
description: |
VisionLabs Backport 3 API. The API version is 4.
OpenAPI specification is the only valid document providing up-to-date information about the service API.
The specification can be used:
- By documentation generation tools to visualize the API.
- By code generation tools.
All the documents and code generated using this specification can include inaccuracies and should be carefully checked.
OpenAPI specification can be received using the "/docs/spec" resource. The "Accept" header should be set to "application/x-yaml".
servers:
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/visionlabs/Luna3API/v.0.3.39
components:
headers:
application_json:
schema:
type: string
enum:
- application/json
required: true
description: content type is application/json
octet_stream:
schema:
type: string
enum:
- application/octet-stream
required: true
description: content type is application/octet-stream
text_plain:
schema:
type: string
enum:
- text/plain
required: true
description: content type is text/plain
image_content_type:
schema:
type: string
enum:
- image/jpeg
- image/png
description: content type is image/jpeg or image/png
required: true
luna_request_id:
schema:
type: string
format: timestamp,uuid4
example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$
description: request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
required: true
application_zip:
schema:
type: string
enum:
- application/zip
required: true
description: content type is application/zip
docs_content_type:
schema:
type: string
enum:
- application/x-yaml
- text/html
required: true
description: Type of recieving data
text_html:
schema:
type: string
enum:
- text/html
required: true
description: content type is text/html
content_disposition:
schema:
type: string
example: 'attachment; filename=task_146.zip'
required: true
description: content disposition with filename
allow_methods:
schema:
type: string
example: 'PUT, DELETE, GET, OPTIONS'
required: true
description: allow methods header
access_control_allow_origin:
schema:
type: string
enum: ['*']
example: '*'
description: access control allow origin header. Is supported by CORS requests to the server
access_control_allow_headers:
schema:
type: string
enum: ['*']
example: '*'
description: access control allow headers. Is supported by CORS requests to the server
access_control_allow_methods:
schema:
type: string
enum: ['*']
example: '*'
description: access control allow methods. Is supported by CORS requests to the server
access_control_max_age:
schema:
type: string
enum: ['86400']
example: '86400'
description: access control max age header. Is supported by CORS requests to the server
config_accept_content_type:
schema:
type: string
enum:
- application/json
- text/plain
required: false
description: The content type of the response body.
parameters:
page:
in: query
name: page
schema:
type: integer
minimum: 1
default: 1
description: a page number.
page_size:
in: query
name: page_size
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: the number of items on page.
accept_docs_handler:
in: header
name: Accept
schema:
$ref: '#/components/schemas/accept_docs_handler'
description: acceptable type of recieving data
luna_request_id:
in: header
schema:
type: string
format: timestamp,uuid4
example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$
description: |
external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
If it was not set, system will set it in default format ("timestamp,UUID4"). It will be returned with response.
name: Luna-Request-Id
application_json_content:
in: header
name: Content-Type
schema:
type: string
enum:
- application/json
description: content type is application/json.
basic_auth_header:
in: header
name: Authorization
schema:
type: string
description: |
Base64-encoded "username:password" credentials
example: Basic login:password(base64)
description: basic authorization header
estimate_attributes:
in: query
name: estimate_attributes
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to estimate basic face attributes (age, gender) from the image.
Attributes are typically floating point probabilities in [0..1] range.
The attributes are stored in *attributes* object per face.
estimate_emotions:
in: query
name: estimate_emotions
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to estimate emotions from the image.
estimate_ethnicities:
in: query
name: estimate_ethnicities
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to estimate ethnicities from the image.
estimate_quality:
in: query
name: estimate_quality
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to estimate image quality from the image.
The estimated quality values is a floating point probability in [0..1] range.
The quality is stored in *quality* parameter per face.
score_threshold:
in: query
name: score_threshold
schema:
allOf:
- $ref: '#/components/schemas/number01'
- default: 0
- description: |
Descriptor quality score threshold.
All the face descriptors with quality score below the threshold will be ignored (and not stored in the DB).
The function will proceed as usual with all the remaining descriptors (if left).
warped_image:
in: query
name: warped_image
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether input image is a warped or arbitrary image.
Exact image warping algorithm is proprietary and this flag is intended for VisionLabs front end tools.
The warped image has the following properties:
it's size is always 250x250 pixels
it's always in RGB color format
it always contains just a single face
the face is always centered and rotated so that imaginary line between the eyes is horizontal.
extract_descriptor:
in: query
name: extract_descriptor
schema:
allOf:
- default: 1
- $ref: '#/components/schemas/int01'
- description: |
Whether to extract face descriptor(s).
Useful when face descriptor is not actually required and only face detection bounding rectangle (with optional attributes and quality estimation) is enough.
Note, that in this case face structure will lack the *id* member.
estimate_head_pose:
in: query
name: estimate_head_pose
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to estimate head pose from the image.
Ignored with warped images (see *warped_image* parameter).
pitch_threshold:
in: query
name: pitch__lt
schema:
type: number
minimum: 0
maximum: 180
example: 10
description: |
Pitch threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted.
Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.
yaw_threshold:
in: query
name: yaw__lt
schema:
type: number
minimum: 0
maximum: 180
example: 10
description: |
Yaw threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted.
Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.
roll_threshold:
in: query
name: roll__lt
schema:
type: number
minimum: 0
maximum: 180
example: 10
description: |
Roll threshold. For all the detections with estimated pitch that's more than threshold, the descriptor will not be extracted.
Threshold must be in degrees, in the interval [0,180]. Otherwise, threshold is not taken into account.
extract_exif:
in: query
name: extract_exif
schema:
allOf:
- $ref: '#/components/schemas/int01'
- description: |
Whether to extract EXIF meta information from input JPEG images.
Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.
This function will only parse the tags and output their names and values as is.
Please refer to [JEITA CP-3451 EXIF specification](http://www.exif.org/Exif2-2.PDF) specification for details.
descriptor_id_in_path:
in: path
name: descriptor_id
schema:
$ref: '#/components/schemas/uuid4'
required: true
description: Face descriptor unique identifier.
descriptor_id_with_thumbnails_in_path:
in: path
name: descriptor_id_with_thumbnails
schema:
type: string
pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}[_][0-9]+$'
required: true
description: |
Face descriptor unique identifier with thumbnail version specified.
Thumbnails are reduced-size versions of portraits. Each thumbnail corresponds to a number equal to the side with maximum length.
The following thumbnail versions are only supported: `_32`, `_64`, `_96`, `_160`.
token_id_uri:
in: path
name: token_id
schema:
$ref: '#/components/schemas/token'
description: Token unique id.
required: true
user_data:
in: query
name: user_data
schema:
$ref: '#/components/schemas/user_data'
required: false
description: find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.
external_id:
in: query
name: external_id
schema:
$ref: '#/components/schemas/person_external_id'
required: false
description: External ID. When filtering by an external ID, you must specify the full external_id value.
descriptor_id:
in: query
name: descriptor_id
schema:
$ref: '#/components/schemas/uuid4'
required: true
description: Face descriptor unique identifier.
do:
in: query
name: do
schema:
$ref: '#/components/schemas/do'
required: true
description: action - attach or detach descriptor to/from person
list_type:
in: query
name: type
schema:
type: string
description: List data type - `persons` or `descriptors`.
default: persons
enum: [persons, descriptors]
required: false
description: List data type - persons or descriptors.
list_id_uri:
in: path
name: list_id
schema:
$ref: '#/components/schemas/list_id'
required: true
description: List id.
person_id_uri:
in: path
name: person_id
schema:
$ref: '#/components/schemas/uuid4'
required: true
description: person id (person_id received in the "create person" request)
candidates_descriptor_ids:
in: query
name: descriptor_ids
schema:
type: string
format: list of uuid
description: Comma-separated list of candidate descriptor ids
candidates_person_ids:
in: query
name: person_ids
schema:
type: string
format: list of uuid
description: Comma-separated list of candidate person ids
reference_descriptor_id:
in: query
name: descriptor_id
schema:
$ref: '#/components/schemas/descriptor_id'
description: reference descriptor id
reference_person_id:
in: query
name: person_id
schema:
$ref: '#/components/schemas/person_id'
description: reference person id
candidates_list_id:
in: query
name: list_id
schema:
$ref: '#/components/schemas/list_id'
description: Candidates list id
verify_descriptor_id:
in: query
name: descriptor_id
schema:
$ref: '#/components/schemas/descriptor_id'
description: descriptor id for verification
required: true
verify_person_id:
in: query
name: person_id
schema:
$ref: '#/components/schemas/person_id'
description: person id for verification
required: true
input_extract_data:
in: header
name: Content-Type
schema:
type: string
enum:
- image/jpeg
- image/png
- image/bmp
- image/tiff
- image/gif
- image/x-windows-bmp
- image/x-portable-pixmap
- application/x-vl-face-descriptor
- application/x-vl-xpk
- image/x-jpeg-base64
- image/x-png-base64
- image/x-bmp-base64
- image/x-tiff-base64
- image/x-gif-base64
- image/x-windows-bmp-base64
- image/x-portable-pixmap-base64
- application/x-vl-face-descriptor-base64
- application/x-vl-xpk-base64
description: An indicator of the media type of the request body.
required: true
limit:
in: query
name: limit
schema:
$ref: '#/components/schemas/match_limit'
do_list:
in: query
name: do
schema:
$ref: '#/components/schemas/do'
required: true
description: action - attach or detach an object to/from a list
list_id_que_req:
in: query
name: list_id
schema:
$ref: '#/components/schemas/list_id'
required: true
description: List id.
multiple_images_content_type:
in: header
name: Content-Type
schema:
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
no_cache:
in: query
name: no_cache
schema:
$ref: '#/components/schemas/int01'
required: false
description: Whether to force database query for fetching data for handler.
json_or_msgpack_content:
in: header
name: Content-Type
schema:
type: string
enum:
- application/json
- application/msgpack
description: Format of a request body data
aggregate_liveness:
in: query
name: aggregate
schema:
type: integer
enum: [1, 0]
default: 0
description: whether to aggregate liveness estimations.
example: 1
cors_origin:
in: header
name: Origin
schema:
type: string
example: 'http://example.com'
description: The Origin header indicates the origin of the cross-site access request
include_luna_services:
in: query
name: include_luna_services
schema:
type: integer
enum: [0, 1]
default: 0
description: whether to perform healthchecks for dependent luna services.
accept_config_handler:
in: header
name: Accept
schema:
type: string
enum:
- application/json
- text/plain
description: One of application/json, text/plain
required: false
description: acceptable type of receiving data
schemas:
Error:
type: object
properties:
error_code:
type: integer
description: error code.
detail:
type: string
description: error details.
required:
- error_code
- detail
example:
error_code: 1
detail: internal server error
int_version:
type: integer
minimum: 0
int01:
type: integer
default: 0
enum: [0,1]
int0180:
type: integer
minimum: 0
maximum: 180
number01:
type: number
format: double
minimum: 0
maximum: 1
example: 0.95
count:
type: integer
minimum: 0
example: 1
time:
type: string
format: date-time
example: "2018-08-11T09:11:41.674Z"
description: time in format RFC 3339
age:
type: integer
minimum: 0
maximum: 100
example: 30
similarity:
type: number
format: double
description: |
Similarity with the reference descriptor.
* 1 means that descriptros are obtained from identical images
* numbers close to 1 mean the descriptors a from the same person
* numbers close to 0 mean the descriptors a from different persons
minimum: 0
maximum: 1
example: 0.95
accept_docs_handler:
type: string
enum:
- application/x-yaml
- text/html
description: One of application/x-yaml, text/html
base_version_schema:
type: object
properties:
major:
allOf:
- $ref: '#/components/schemas/int_version'
- description: a major version of service.
minor:
allOf:
- $ref: '#/components/schemas/int_version'
- description: a minor version of service.
patch:
allOf:
- $ref: '#/components/schemas/int_version'
- description: a patch version of service.
required: [major, minor, patch]
example:
major: 1
minor: 3
patch: 2
version:
allOf:
- properties:
api:
allOf:
- $ref: '#/components/schemas/int_version'
- description: an api version of service.
- $ref: '#/components/schemas/base_version_schema'
- required: [api, major, minor, patch]
example:
api: 1
major: 0
minor: 0
patch: 0
organization_name:
type: string
maxLength: 128
description: organization name
example: Horns and hooves
email:
type: string
maxLength: 64
format: email
description: email address
example: hornsandhooves@ya.ru
password:
type: string
minLength: 8
maxLength: 32
description: account password
example: strong_password
account_status:
type: boolean
description: Account status - suspended (true) or active (false).
example: true
uuid4:
type: string
format: uuid4
pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$'
example: "557d54ec-29ad-4f3c-93b4-c9092ef12515"
user_data:
description: User-defined data. Arbitrary string.
type: string
maxLength: 128
example: "info"
person_external_id:
description: External id of the person, if it has its own mapping in external system.
type: string
maxLength: 36
example: "14159261415926"
person_id:
allOf:
- description: Person identifier.
- $ref: '#/components/schemas/uuid4'
descriptor_id:
allOf:
- $ref: '#/components/schemas/uuid4'
description: Face descriptor identifier.
list_id:
allOf:
- $ref: '#/components/schemas/uuid4'
- description: List id. uuid4
do:
type: string
enum: [attach, detach]
description: action to perform - attach or detach
token:
allOf:
- $ref: '#/components/schemas/uuid4'
- description: API token.
example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"
new_account:
type: object
properties:
organization_name:
$ref: '#/components/schemas/organization_name'
email:
$ref: '#/components/schemas/email'
password:
$ref: '#/components/schemas/password'
required: [organization_name, email, password]
account:
type: object
properties:
organization_name:
$ref: '#/components/schemas/organization_name'
email:
$ref: '#/components/schemas/email'
suspended:
$ref: '#/components/schemas/account_status'
required: [organization_name, email, suspended]
verification_status:
type: boolean
description: |
status of verification. `true` - the service assumes that a reference and candidates are same person.
ethnicities_estimations:
type: object
description: Ethnicity classifier response.
properties:
asian:
allOf:
- description: Asian ethnicity probability.
- $ref: '#/components/schemas/number01'
indian:
allOf:
- description: Indian ethnicity probability.
- $ref: '#/components/schemas/number01'
caucasian:
allOf:
- description: Caucasian ethnicity probability.
- $ref: '#/components/schemas/number01'
african_american:
allOf:
- description: African American ethnicity probability.
- $ref: '#/components/schemas/number01'
required: [african_american, caucasian, indian, asian]
ethnicities:
description: Ethnicities estimation.
type: object
properties:
estimations:
$ref: '#/components/schemas/ethnicities_estimations'
predominant_ethnicity:
type: string
description: Name of predominant ethnicity.
enum: [african_american, caucasian, indian, asian]
required: [estimations, predominant_ethnicity]
example:
estimations:
african_american: 1.92238889737406e-12
asian: 0.954671621322632
caucasian: 0.045328326523304
indian: 7.65100649502415e-10
predominant_ethnicity: "asian"
emotions_estimations:
type: object
description: Emotion classifier response.
properties:
anger:
allOf:
- description: Anger probability.
- $ref: '#/components/schemas/number01'
disgust:
allOf:
- description: Disgust probability.
- $ref: '#/components/schemas/number01'
fear:
allOf:
- description: Fear probability.
- $ref: '#/components/schemas/number01'
happiness:
allOf:
- description: Happiness probability.
- $ref: '#/components/schemas/number01'
neutral:
allOf:
- description: Neutral probability.
- $ref: '#/components/schemas/number01'
sadness:
allOf:
- description: Sadness probability.
- $ref: '#/components/schemas/number01'
surprise:
allOf:
- description: Suprise probability.
- $ref: '#/components/schemas/number01'
required: [surprise, sadness, neutral, happiness, fear, disgust, anger]
emotions:
type: object
properties:
estimations:
$ref: '#/components/schemas/emotions_estimations'
predominant_emotion:
type: string
description: name of predominant emotion.
enum: [happiness, surprise, sadness, neutral, fear, disgust, anger]
required: [estimations, predominant_emotion]
example:
estimations:
happiness: 0.954671621322632
surprise: 0.045328326523304
sadness: 7.65100649502415e-10
neutral: 1.92238889737406e-12
fear: 0
disgust: 0
anger: 0
predominant_emotion: "happiness"
head_pose:
type: object
properties:
yaw:
type: number
description: Yaw rotation in degrees.
pitch:
type: number
description: Pitch rotation in degrees.
roll:
type: number
description: Roll rotation in degrees.
required: [yaw, pitch, roll]
example:
yaw: 0
pitch: 2
roll: 1
rect:
description: Bounding rectangle.
type: object
properties:
height:
type: integer
description: Rectangle height.
format: int32
example: 200
width:
type: integer
description: Rectangle width.
format: int32
example: 100
x:
type: integer
description: Top left corner "x" coordinate.
format: int32
example: 17
y:
type: integer
description: Top left corner "y" coordinate.
format: int32
example: 10
required: [height, width, x, y]
example:
height: 240
width: 209
x: 170
y: 198
quality:
description: |
Image quality. Estimation of image visual properties.
type: object
properties:
dark:
allOf:
- description: Low value means underlit face area (i.e. due to backlight, poor lighting, sensor underexposure).
- $ref: '#/components/schemas/number01'
light:
allOf:
- description: Low value means overlit face area (i.e. overbright lighting, sensor overexposure).
- $ref: '#/components/schemas/number01'
saturation:
allOf:
- description: |
Low value means low saturation (e.g. grayscale images).
> **WARNING** Estimation of *saturation* property is no longer supported, and the value is always set to 1.
- $ref: '#/components/schemas/number01'
blurriness:
allOf:
- description: Low value means blurred image (e.g. due to depth of field or motion blur). High value means sharp image.
- $ref: '#/components/schemas/number01'
required: [dark, light, saturation, blurriness]
example:
light: 0.87
dark: 0.13
saturation: 1
blurriness: 0.2
estimated_attributes:
type: object
properties:
age:
allOf:
- description: Age estimation (in years).
- $ref: '#/components/schemas/age'
gender:
allOf:
- description: |
Gender estimation.
- 0 - female
- 1 - male
- $ref: '#/components/schemas/int01'
ethnicities:
allOf:
- description: Face ethnicities estimation.
- $ref: '#/components/schemas/ethnicities'
emotions:
allOf:
- description: Face emotions estimation.
- $ref: '#/components/schemas/emotions'
head_pose:
allOf:
- description: Head pose estimation.
- $ref: '#/components/schemas/head_pose'
created_face:
type: object
properties:
id:
allOf:
- description: Face descriptor unique identifier.
- $ref: '#/components/schemas/uuid4'
rect:
allOf:
- description: Face detection bounding box.
- $ref: '#/components/schemas/rect'
rectISO:
allOf:
- description: Face portrait bounding box.
- $ref: '#/components/schemas/rect'
score:
allOf:
- description: Face descriptor quality score.
- $ref: '#/components/schemas/number01'
attributes:
allOf:
- description: |
Face attributes estimation.
> **WARNING** Estimation of *eyeglasses* attribute is no longer supported
- $ref: '#/components/schemas/estimated_attributes'
quality:
allOf:
- description: Image quality estimation for this face detection region.
- $ref: '#/components/schemas/quality'
exif:
description: |
select image EXIF tags.
See [CIPA DC-008-2016]( http://www.cipa.jp/std/documents/e/DC-008-Translation-2016-E.pdf) for details.
Tag to string conversions is handled by libEXIF.
type: object
properties:
make:
type: string
description: make tag (IFD0 0x010f).
model:
type: string
description: model tag (IFD0 0x0110).
gps:
type: object
properties:
latitude:
type: string
description: |
GPS latitude (IFD GPS).
Combined latitude ref (0x0001) + latitude (0x0002).
longitude:
type: string
description: |
GPS longitude (IFD GPS).
Combined longitude ref (0x0003) + longitude (0x0004).
required: [latitude, longitude]
artist:
type: string
description: artist tag (IFD0 0x013b).
software:
type: string
description: software tag (IFD0 0x0131).
flash:
type: string
description: flash tag (IFD_EXIF 0x9209)
orientation:
type: integer
description: orientation (IFD0 0x0112).
example:
artist: "Photomaker Vadim"
model: "Canon PX-200"
software: "Adobe Photoshop CS5 Macintosh"
extractor_response:
type: object
properties:
faces:
type: array
minItems: 1
items:
$ref: '#/components/schemas/created_face'
exif:
$ref: '#/components/schemas/exif'
required: [faces]
descriptor_last_update:
allOf:
- $ref: '#/components/schemas/time'
description: |
Last update date and time with timezone. Initially will contain descriptor creation time.
Once attached or detached, this value is updated with operation timestamp.
descriptor_info:
type: object
properties:
id:
allOf:
- description: Face descriptor unique identifier.
- $ref: '#/components/schemas/uuid4'
last_update:
$ref: '#/components/schemas/descriptor_last_update'
person_id:
allOf:
- description: Person ID (if attached to a person)
- $ref: '#/components/schemas/uuid4'
- nullable: true
lists:
description: List of Luna lists, which contain the descriptor.
type: array
items:
$ref: '#/components/schemas/list_id'
required: [id, last_update, person_id, lists]
descriptors_response:
type: object
properties:
descriptors:
type: array
items:
$ref: '#/components/schemas/descriptor_info'
count:
allOf:
- $ref: '#/components/schemas/count'
description: Total count of descriptors owned by current account.
required: [descriptors, count]
token_data:
type: string
description: User data about token. Arbitrary string.
maxLength: 128
example: "For south camera"
get_account_tokens_response:
type: object
properties:
tokens:
type: array
items:
type: object
properties:
token_data:
$ref: '#/components/schemas/token_data'
id:
$ref: '#/components/schemas/token'
required: [token_data, id]
count:
allOf:
- $ref: '#/components/schemas/count'
- description: Total number of tokens in system.
required: [tokens, count]
post_account_tokens_request:
type: object
properties:
token_data:
$ref: '#/components/schemas/token_data'
required: [token_data]
post_account_tokens_response:
type: object
properties:
token:
$ref: '#/components/schemas/token'
required: [token]
delete_account_tokens_request:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/token'
required: [tokens]
get_account_token_response:
type: object
properties:
token_data:
$ref: '#/components/schemas/token_data'
required: [token_data]
patch_account_tokens_request:
type: object
properties:
token_data:
$ref: '#/components/schemas/token_data'
required: [token_data]
create_person:
type: object
properties:
user_data:
$ref: '#/components/schemas/user_data'
external_id:
$ref: '#/components/schemas/person_external_id'
person_descriptors:
type: array
description: descriptors linked to person
items:
$ref: '#/components/schemas/descriptor_id'
minItems: 0
person_create_time:
allOf:
- $ref: '#/components/schemas/time'
description: Date and time with timezone when the person was created. Format is RFC3339.
person:
type: object
properties:
id:
$ref: '#/components/schemas/person_id'
user_data:
$ref: '#/components/schemas/user_data'
create_time:
$ref: '#/components/schemas/person_create_time'
external_id:
$ref: '#/components/schemas/person_external_id'
descriptors:
$ref: '#/components/schemas/person_descriptors'
lists:
description: List of Luna lists, which contain the person.
type: array
items:
$ref: '#/components/schemas/list_id'
required: [id, user_data, create_time, external_id, descriptors]
persons:
type: array
items:
$ref: '#/components/schemas/person'
minItems: 0
person_count:
allOf:
- $ref: '#/components/schemas/count'
description: Total count of persons.
get_descriptor_lists_response:
type: object
properties:
lists:
description: List of Luna lists, which contain the descriptor.
type: array
items:
$ref: '#/components/schemas/list_id'
required: [lists]
get_person_lists_response:
type: object
properties:
lists:
description: List of Luna lists, which contain the person.
type: array
items:
$ref: '#/components/schemas/list_id'
required: [lists]
list_data_in_get_lists_response:
type: object
properties:
list_data:
$ref: '#/components/schemas/user_data'
count:
allOf:
- $ref: '#/components/schemas/count'
- description: Total number of objects in list.
id:
$ref: '#/components/schemas/list_id'
required: [list_data, count, id]
get_lists_response:
type: object
properties:
lists:
type: object
description: Lists of the account.
properties:
person_lists:
type: array
description: List of person lists.
items:
$ref: '#/components/schemas/list_data_in_get_lists_response'
descriptor_lists:
type: array
description: List of descriptor lists.
items:
$ref: '#/components/schemas/list_data_in_get_lists_response'
required: [person_lists, descriptor_lists]
persons_list_count:
allOf:
- $ref: '#/components/schemas/count'
- description: Total number of person lists.
descriptors_list_count:
allOf:
- $ref: '#/components/schemas/count'
- description: Total number of descriptor lists.
required: [lists, persons_list_count, descriptors_list_count]
post_lists_request:
type: object
properties:
list_data:
$ref: '#/components/schemas/user_data'
patch_list_request:
type: object
properties:
list_data:
$ref: '#/components/schemas/user_data'
required: [list_data]
post_lists_response:
type: object
properties:
list_id:
$ref: '#/components/schemas/list_id'
required: [list_id]
delete_lists_request:
type: object
properties:
lists:
description: Array of lists to delete.
type: array
items:
$ref: '#/components/schemas/list_id'
required: [lists]
get_list_persons_response:
type: object
properties:
persons:
type: array
items:
type: object
properties:
id:
$ref: '#/components/schemas/person_id'
user_data:
$ref: '#/components/schemas/user_data'
create_time:
$ref: '#/components/schemas/person_create_time'
descriptors:
type: array
description: List of all descriptors attached to the person.
items:
$ref: '#/components/schemas/uuid4'
lists:
type: array
description: List of all lists attached to the person.
items:
$ref: '#/components/schemas/uuid4'
external_id:
$ref: '#/components/schemas/person_external_id'
required: [id, user_data, create_time, descriptors, lists, external_id]
list_data:
$ref: '#/components/schemas/user_data'
count:
$ref: '#/components/schemas/count'
required: [persons, list_data, count]
get_list_descriptors_response:
type: object
properties:
descriptors:
type: array
items:
type: object
properties:
id:
$ref: '#/components/schemas/descriptor_id'
last_update:
$ref: '#/components/schemas/descriptor_last_update'
person_id:
allOf:
- description: Person id (if attached to a person).
- $ref: '#/components/schemas/uuid4'
- nullable: true
required: [id, last_update, person_id]
list_data:
$ref: '#/components/schemas/user_data'
count:
$ref: '#/components/schemas/count'
required: [descriptors, list_data, count]
get_list_response:
oneOf:
- $ref: '#/components/schemas/get_list_persons_response'
- $ref: '#/components/schemas/get_list_descriptors_response'
patch_linker_descriptors_request:
type: object
properties:
action:
$ref: '#/components/schemas/do'
descriptor_ids:
type: array
description: Descriptor ids to operate with.
items:
$ref: '#/components/schemas/uuid4'
list_id:
$ref: '#/components/schemas/list_id'
required: [action, descriptor_ids, list_id]
patch_linker_persons_request:
type: object
properties:
action:
$ref: '#/components/schemas/do'
person_ids:
type: array
description: Person ids to operate with.
items:
$ref: '#/components/schemas/uuid4'
list_id:
$ref: '#/components/schemas/list_id'
required: [action, person_ids, list_id]
patch_linker_request:
oneOf:
- $ref: '#/components/schemas/patch_linker_descriptors_request'
- $ref: '#/components/schemas/patch_linker_persons_request'
person_match:
type: object
properties:
person_id:
allOf:
- $ref: '#/components/schemas/person_id'
- description: Matched person identifier
descriptor_id:
allOf:
- $ref: '#/components/schemas/person_id'
- description: Matched descriptor identifier
user_data:
allOf:
- $ref: '#/components/schemas/user_data'
- description: Matched person user data
external_id:
allOf:
- $ref: '#/components/schemas/person_external_id'
similarity:
$ref: '#/components/schemas/similarity'
required: [person_id, user_data, external_id, similarity, descriptor_id]
example:
person_id: "0e05c9c7-9422-43a4-8656-2038b51347c2"
descriptor_id: "83abe9a5-32f6-4e0c-8db2-c2af11ceb30d"
user_data: "M.K."
external_id: "12345rt12"
similarity: 0.945
descriptor_match:
type: object
properties:
similarity:
$ref: '#/components/schemas/similarity'
id:
allOf:
- $ref: '#/components/schemas/person_id'
- description: Matched descriptor identifier
required: [id, similarity]
example:
id: "83abe9a5-32f6-4e0c-8db2-c2af11ceb30d"
similarity: 0.945
match_by_persons_schema:
type: object
properties:
candidates:
type: array
items:
$ref: '#/components/schemas/person_match'
description: array of matching results by persons
required: [candidates]
match_by_descriptors_schema:
type: object
properties:
candidates:
type: array
items:
$ref: '#/components/schemas/descriptor_match'
description: array of matching results by descriptors
required: [candidates]
search_schema:
type: object
properties:
candidates:
anyOf:
- type: array
minItems: 0
items:
$ref: '#/components/schemas/descriptor_match'
description: array of matching results by descriptors
- type: array
minItems: 0
items:
$ref: '#/components/schemas/person_match'
description: array of matching results by persons
face:
$ref: '#/components/schemas/created_face'
exif:
$ref: '#/components/schemas/exif'
required: [candidates, face]
verify_schemas:
type: object
properties:
candidates:
type: array
items:
$ref: '#/components/schemas/person_match'
description: match result
maxItems: 1
required: [candidates]
many_faces_error:
type: object
properties:
error_code:
type: integer
description: error code.
detail:
type: object
properties:
faces:
type: array
minItems: 2
items:
$ref: '#/components/schemas/created_face'
required: [faces]
description: all found faces
required: [error_code, detail]
handler_matching_limit:
type: integer
minimum: 1
maximum: 5
default: 3
description: matching limit
match_limit:
type: integer
minimum: 1
maximum: 5
default: 3
description: maximum of number candidates in a matching response
LivenessMeta:
type: object
required: [OS]
properties:
OS:
type: string
enum: ["IOS", "ANDROID", "DESKTOP", "UNKNOWN"]
description: device OS.
MANUFACTURE:
type: string
description: device manufacturer.
MODEL:
type: string
description: device model.
description: |
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.
liveness_probability:
type: number
format: float
description: |
The parameter shows the probability of a live person being present in the
image, i.e. it is not a presentation attack.
In general, the estimated probability must exceed the theoretical
threshold of 50%. The value may be increased according to your business rules.
example: 0.99
liveness_quality:
type: number
format: float
description: |
Quality value is a probability of "appropriate image".
The parameter describes the integral value of image, facial and environmental characteristics.
example: 1.0
liveness_prediction:
type: integer
enum: [1, 0]
description: prediction that a person is alive (1 - alive, 0 - not)
example: 1
liveness_result:
type: object
description: liveness prediction result
properties:
prediction:
$ref: '#/components/schemas/liveness_prediction'
estimations:
type: object
description: liveness estimations result
properties:
probability:
$ref: '#/components/schemas/liveness_probability'
quality:
$ref: '#/components/schemas/liveness_quality'
required: [probability, quality]
required: [prediction, estimations]
liveness_aggregate_result:
type: object
description: aggregated livess prediction result
properties:
prediction:
$ref: '#/components/schemas/liveness_prediction'
estimations:
type: object
description: aggregated liveness estimations result
properties:
probability:
allOf:
- description: |
Average probability that a live person is present in the image.
In general, the estimated probability must exceed the theoretical
threshold of 50%. The value may be increased according to your business rules.
- $ref: '#/components/schemas/liveness_probability'
quality:
allOf:
- description: |
Average value of estimate quality.
The parameter describes the integral value of image, facial, and environmental characteristics.
Estimated quality must exceed the theoretical threshold of 20%.
The threshold may be increased according to the photo shooting conditions.
- $ref: '#/components/schemas/liveness_quality'
required: [probability, quality]
required: [prediction, estimations]
liveness_response:
type: object
properties:
images:
description: list of processed images
type: array
items:
type: object
properties:
filename:
type: string
example: "claudia.jpg"
description: |
source image file name (preserved only for multipart-form-data and application/json requests,
otherwise "raw_image")
status:
type: integer
enum: [0, 1]
description: image status. 0 - liveness prediction failed, 1 - liveness prediction succeded
liveness:
allOf:
- nullable: true
- $ref: '#/components/schemas/liveness_result'
error:
allOf:
- $ref: '#/components/schemas/Error'
description: errors occurred during the liveness processing
required: [filename, status, liveness, error]
aggregate_estimations:
type: object
description: liveness result with aggregate estimates
properties:
liveness:
$ref: '#/components/schemas/liveness_aggregate_result'
required: [liveness]
required: [images]
example:
images:
- filename: succeeded_image.jpg
status: 1
liveness:
prediction: 1
estimations:
probability: 0.93
quality: 0.95
error:
desc: Success
detail: Success
error_code: 0
- filename: succeeded_image_2.jpg
status: 1
liveness:
prediction: 1
estimations:
probability: 0.85
quality: 0.88
error:
desc: Success
detail: Success
error_code: 0
- filename: failed_image.jpg
status: 0
liveness: null
error:
desc: Failed to decode image data
detail: Failed to decodeImage image data.
error_code: 3001
aggregate_estimations:
liveness:
prediction: 1
estimations:
probability: 0.89
quality: 0.915
image_binary_for_multipart:
type: string
format: binary
description: |
Binary image.
Content-Disposition header must contain actual filename.
Filenames are used to differentiate images, they must be unique within the request.
This part must have valid Content-Type header (one of "image/jpeg", "image/png", "image/bmp", "image/tiff",
"image/x-portable-pixmap")
image_base64_for_multipart:
type: string
description: |
Image encoded in base64.
This part must have valid Content-Type header (one of "image/x-jpeg-base64", "image/x-png-base64",
"image/x-bmp-base64", "image/x-tiff-base64", "image/x-portable-pixmap-base64")
image_for_multipart:
oneOf:
- $ref: '#/components/schemas/image_binary_for_multipart'
- $ref: '#/components/schemas/image_base64_for_multipart'
image_list_for_multipart:
type: array
items:
$ref: '#/components/schemas/image_for_multipart'
minItems: 1
ListOfUrlsWithImages:
type: array
items:
type: string
format: uri
minItems: 1
maxItems: 8
description: list of urls with images
example:
- "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c4/Abbey_Lee_2015.jpg/800px-Abbey_Lee_2015.jpg"
- "https://upload.wikimedia.org/wikipedia/commons/thumb/2/2d/Yfke-sturm-1326186044.jpg/800px-Yfke-sturm-1326186044.jpg"
match_vs_descriptor:
type: object
required: ["id", "similarity"]
properties:
id:
allOf:
- description: Face descriptor unique identifier.
- $ref: '#/components/schemas/uuid4'
similarity:
$ref: '#/components/schemas/similarity'
example:
id : "15fd2706-8baf-433b-82eb-8c7fada847da"
similarity: 0.761
match_vs_person:
type: object
required: ["person_id", "similarity", "user_data", "descriptor_id", "external_id"]
properties:
person_id:
$ref: '#/components/schemas/person_id'
similarity:
$ref: '#/components/schemas/similarity'
user_data:
$ref: '#/components/schemas/user_data'
descriptor_id:
$ref: '#/components/schemas/descriptor_id'
external_id:
$ref: '#/components/schemas/person_external_id'
example:
person_id : "15fd2706-8baf-433b-82eb-8c7fada847da"
similarity: 0.761
user_data: "user data"
descriptor_id: "137d2706-8baf-433b-82eb-8c7fada847da"
external_id: ""
extracted_face_base:
type: object
properties:
id:
allOf:
- description: Face descriptor unique identifier.
- $ref: '#/components/schemas/uuid4'
score:
allOf:
- description: Face descriptor quality score.
- $ref: '#/components/schemas/number01'
extracted_face:
allOf:
- $ref: '#/components/schemas/extracted_face_base'
- type: object
required: ["id", "rect", "rectISO", "score"]
properties:
rect:
allOf:
- description: Face detection bounding box.
- $ref: '#/components/schemas/rect'
rectISO:
allOf:
- description: Face portrait bounding box.
- $ref: '#/components/schemas/rect'
attributes:
allOf:
- description: |
Face attributes estimation.
> **WARNING** Estimation of *eyeglasses* attribute is no longer supported
- $ref: '#/components/schemas/estimated_attributes'
quality:
allOf:
- description: Image quality estimation for this face detection region.
- $ref: '#/components/schemas/quality'
example:
id: "16fd2706-8baf-433b-82eb-8c7fada847da"
rect:
height: 240
width: 209
x: 170
y: 198
rectISO:
height: 421
width: 316
x: 123
y: 10
score: 0.5
extracted_face_warp:
allOf:
- $ref: '#/components/schemas/extracted_face_base'
- required: ["id", "score"]
example:
id: "16fd2706-8baf-433b-82eb-8c7fada847da"
score: 0.44
extracted_face_raw_data:
type: object
properties:
id:
allOf:
- description: Face descriptor unique identifier.
- $ref: '#/components/schemas/uuid4'
required: ["id"]
handler_id:
allOf:
- $ref: '#/components/schemas/uuid4'
description: Handler identifier.
handler_type:
type: string
enum: [extractor, identify, verify]
description: handler type
handler_version:
type: integer
minimum: 1
description: handler version (increase after patch)
estimate_attributes:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: whether to estimate basic attributes on the image.
estimate_emotions:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: whether to estimate emotions on the image.
estimate_ethnicities:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: whether to estimate ethnicities on the image.
estimate_quality:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: whether to estimate input face image quality.
estimate_head_pose:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: whether to estimate head pose on the image.
extract_exif:
allOf:
- $ref: '#/components/schemas/int01'
- type: integer
- description: |
whether to extract EXIF meta information from input JPEG images.
Exact output will vary since there are no mandatory requirements to both authoring software and digital cameras how to write the data.
This function will only parse the tags and output their names and values as is. Please refer to JEITA CP-3451 EXIF specification for details.
pitch_threshold:
allOf:
- $ref: '#/components/schemas/int0180'
- type: integer
- description: |
maximum deviation pitch angle from 0.
- example: 35
roll_threshold:
allOf:
- $ref: '#/components/schemas/int0180'
- type: integer
- description: |
maximum deviation roll angle from 0.
- example: 45
yaw_threshold:
allOf:
- $ref: '#/components/schemas/int0180'
- type: integer
- description: |
maximum deviation yaw angle from 0.
- example: 55
threshold:
type: number
minimum: 0
maximum: 1
example: 0.9
score_threshold:
allOf:
- $ref: '#/components/schemas/threshold'
description: |
descriptor quality score threshold. All the attributes with quality score below the threshold will be
ignored (and not stored in the DB). The function will proceed as usual with all the remaining descriptors
(if left).
identify_threshold:
allOf:
- $ref: '#/components/schemas/threshold'
description: |
Identify threshold. Face with matching score under threshold will be ignored.
verify_threshold:
allOf:
- $ref: '#/components/schemas/threshold'
description: |
Verify threshold.
Face with matching score under threshold will be ignored (negative status of verification), but still
exists in list of candidates.
extractor_handler_policies:
type: object
properties:
list_id:
$ref: '#/components/schemas/list_id'
estimate_attributes:
$ref: '#/components/schemas/estimate_attributes'
estimate_emotions:
$ref: '#/components/schemas/estimate_emotions'
estimate_ethnicities:
$ref: '#/components/schemas/estimate_ethnicities'
estimate_quality:
$ref: '#/components/schemas/estimate_quality'
estimate_head_pose:
$ref: '#/components/schemas/estimate_head_pose'
extract_exif:
$ref: '#/components/schemas/extract_exif'
yaw_threshold:
$ref: '#/components/schemas/yaw_threshold'
roll_threshold:
$ref: '#/components/schemas/roll_threshold'
pitch_threshold:
$ref: '#/components/schemas/pitch_threshold'
score_threshold:
$ref: '#/components/schemas/score_threshold'
description: extractor handler policies
extractor_handler_policies_request:
allOf:
- $ref: '#/components/schemas/extractor_handler_policies'
minProperties: 1
extractor_handler_policies_response:
allOf:
- $ref: '#/components/schemas/extractor_handler_policies'
required: [list_id, estimate_attributes, estimate_emotions, estimate_ethnicities, estimate_quality,
estimate_head_pose, extract_exif, yaw_threshold, roll_threshold, pitch_threshold, score_threshold]
extractor_handler_response:
type: object
properties:
handler_id:
$ref: '#/components/schemas/handler_id'
create_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler create time
last_update_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler last update time
policies:
$ref: '#/components/schemas/extractor_handler_policies_response'
type:
allOf:
- $ref: '#/components/schemas/handler_type'
- enum: [extractor]
version:
$ref: '#/components/schemas/handler_version'
required: [handler_id, create_time, last_update_time, policies, type, version]
identify_handler_policies:
type: object
properties:
list_id:
$ref: '#/components/schemas/list_id'
limit:
$ref: '#/components/schemas/handler_matching_limit'
estimate_attributes:
$ref: '#/components/schemas/estimate_attributes'
estimate_emotions:
$ref: '#/components/schemas/estimate_emotions'
estimate_ethnicities:
$ref: '#/components/schemas/estimate_ethnicities'
estimate_quality:
$ref: '#/components/schemas/estimate_quality'
estimate_head_pose:
$ref: '#/components/schemas/estimate_head_pose'
extract_exif:
$ref: '#/components/schemas/extract_exif'
yaw_threshold:
$ref: '#/components/schemas/yaw_threshold'
roll_threshold:
$ref: '#/components/schemas/roll_threshold'
pitch_threshold:
$ref: '#/components/schemas/pitch_threshold'
score_threshold:
$ref: '#/components/schemas/score_threshold'
identify_threshold:
$ref: '#/components/schemas/identify_threshold'
description: identify handler policies
identify_handler_policies_request:
allOf:
- $ref: '#/components/schemas/identify_handler_policies'
minProperties: 1
identify_handler_policies_response:
allOf:
- $ref: '#/components/schemas/identify_handler_policies'
required: [list_id, limit, estimate_attributes, estimate_emotions, estimate_ethnicities, estimate_quality,
estimate_head_pose, extract_exif, yaw_threshold, roll_threshold, pitch_threshold, score_threshold,
identify_threshold]
identify_handler_response:
type: object
properties:
handler_id:
$ref: '#/components/schemas/handler_id'
create_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler create time
last_update_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler last update time
policies:
$ref: '#/components/schemas/identify_handler_policies_response'
type:
allOf:
- $ref: '#/components/schemas/handler_type'
- enum: [identify]
version:
$ref: '#/components/schemas/handler_version'
required: [handler_id, create_time, last_update_time, policies, type, version]
verify_handler_policies:
type: object
properties:
estimate_attributes:
$ref: '#/components/schemas/estimate_attributes'
estimate_emotions:
$ref: '#/components/schemas/estimate_emotions'
estimate_ethnicities:
$ref: '#/components/schemas/estimate_ethnicities'
estimate_quality:
$ref: '#/components/schemas/estimate_quality'
estimate_head_pose:
$ref: '#/components/schemas/estimate_head_pose'
extract_exif:
$ref: '#/components/schemas/extract_exif'
yaw_threshold:
$ref: '#/components/schemas/yaw_threshold'
roll_threshold:
$ref: '#/components/schemas/roll_threshold'
pitch_threshold:
$ref: '#/components/schemas/pitch_threshold'
score_threshold:
$ref: '#/components/schemas/score_threshold'
verify_threshold:
$ref: '#/components/schemas/verify_threshold'
description: verify handler policies
verify_handler_policies_request:
allOf:
- $ref: '#/components/schemas/verify_handler_policies'
minProperties: 1
verify_handler_policies_response:
allOf:
- $ref: '#/components/schemas/verify_handler_policies'
required: [estimate_attributes, estimate_emotions, estimate_ethnicities, estimate_quality,
estimate_head_pose, extract_exif, yaw_threshold, roll_threshold, pitch_threshold, score_threshold,
verify_threshold]
verify_handler_response:
type: object
properties:
handler_id:
$ref: '#/components/schemas/handler_id'
create_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler create time
last_update_time:
allOf:
- $ref: '#/components/schemas/time'
description: handler last update time
policies:
$ref: '#/components/schemas/verify_handler_policies_response'
type:
allOf:
- $ref: '#/components/schemas/handler_type'
- enum: [verify]
version:
$ref: '#/components/schemas/handler_version'
required: [handler_id, create_time, last_update_time, policies, type, version]
patch_handler_response:
type: object
properties:
version:
$ref: '#/components/schemas/handler_version'
required: [version]
handler_verification_response:
type: object
required: ["status", "candidates", "face"]
properties:
status:
$ref: '#/components/schemas/verification_status'
candidates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/match_vs_person'
face:
oneOf:
- $ref: '#/components/schemas/extracted_face'
- $ref: '#/components/schemas/extracted_face_warp'
- $ref: '#/components/schemas/extracted_face_raw_data'
exif:
$ref: '#/components/schemas/exif'
descriptor_version:
type: integer
description: the descriptor version
enum: [46, 52, 54, 56, 57, 58, 59]
example: 56
raw_descriptor:
type: string
format: byte
description: raw descriptor encoded in base64
example: 2xQ2gprbMUePw1s9gw9fvA==
descriptor_data:
type: object
description: descriptor and descriptor version
properties:
descriptor:
$ref: '#/components/schemas/raw_descriptor'
version:
$ref: '#/components/schemas/descriptor_version'
required: [descriptor, version]
sdk_descriptor_base64:
type: string
format: byte
description: Luna SDK descriptor encoded in Base64. The descriptor version, a signuture and descriptor.
descriptor_base64:
oneOf:
- $ref: '#/components/schemas/descriptor_data'
- $ref: '#/components/schemas/sdk_descriptor_base64'
common_id:
description: user-defined id.
type: string
maxLength: 36
example: "3.1415926"
raw_match_reference_id:
allOf:
- $ref: '#/components/schemas/common_id'
- description: reference id for identification in the match results
- example: 123456s
raw_match_candidate_id:
allOf:
- $ref: '#/components/schemas/common_id'
- description: candidate id for identification in the match results
- example: 56789t
xpk_file:
type: string
format: binary
description: xpk file with descriptors
sdk_descriptor:
type: string
format: binary
description: luna sdk descriptor in bytes. The descriptor version, a signuture and descriptor.
identification_id:
allOf:
- $ref: '#/components/schemas/common_id'
- description: id for identification in the match results
- example: 3456d
raw_descriptor_entity:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["raw_descriptor"]
data:
$ref: '#/components/schemas/descriptor_data'
required: [id, type, data]
sdk_descriptor_entity:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["sdk_descriptor"]
description: type corresponds to a `x-vl-face-descriptor` content type
data:
$ref: '#/components/schemas/sdk_descriptor'
required: [id, type, data]
xpk_file_entity:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["xpk_file"]
description: type corresponds to a `application/x-vl-xpk` content type
data:
$ref: '#/components/schemas/xpk_file'
required: [id, type, data]
raw_descriptor_entity_binary:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["raw_descriptor"]
data:
$ref: '#/components/schemas/descriptor_data'
required: [id, type, data]
sdk_descriptor_entity_binary:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["sdk_descriptor"]
description: type corresponds to a `x-vl-face-descriptor` content type
data:
$ref: '#/components/schemas/sdk_descriptor'
required: [id, type, data]
xpk_file_entity_binary:
type: object
properties:
id:
$ref: '#/components/schemas/identification_id'
type:
type: string
enum: ["xpk_file"]
description: type corresponds to a `application/x-vl-xpk` content type
data:
$ref: '#/components/schemas/xpk_file'
required: [id, type, data]
raw_batch_verification_request_json:
type: object
properties:
references:
type: array
items:
oneOf:
- $ref: '#/components/schemas/xpk_file_entity'
- $ref: '#/components/schemas/sdk_descriptor_entity'
- $ref: '#/components/schemas/raw_descriptor_entity'
description: reference list for verification
minItems: 1
candidates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/xpk_file_entity'
- $ref: '#/components/schemas/sdk_descriptor_entity'
- $ref: '#/components/schemas/raw_descriptor_entity'
minItems: 1
description: candidates for verification
required: [references, candidates]
raw_batch_verification_request_msgpack:
type: object
properties:
references:
type: array
items:
oneOf:
- $ref: '#/components/schemas/xpk_file_entity_binary'
- $ref: '#/components/schemas/sdk_descriptor_entity_binary'
- $ref: '#/components/schemas/raw_descriptor_entity_binary'
description: reference list for verification
minItems: 1
candidates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/xpk_file_entity_binary'
- $ref: '#/components/schemas/sdk_descriptor_entity_binary'
- $ref: '#/components/schemas/raw_descriptor_entity_binary'
minItems: 1
description: candidates for verification
required: [references, candidates]
raw_batch_verification_response:
type: object
properties:
matches:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/raw_match_reference_id'
matches:
type: array
items:
description: sorted list with success match result for the *reference_id* vs candidate batch.
type: object
properties:
candidate_id:
$ref: '#/components/schemas/raw_match_candidate_id'
similarity:
$ref: '#/components/schemas/similarity'
status:
$ref: '#/components/schemas/verification_status'
required: [candidate_id, similarity, status]
minItems: 1
description: reference vs candidates matches
required: [reference_id, matches]
description: list of matches
required: [matches]
health_ok:
description: successful healthcheck execution info
type: object
properties:
execution_time:
type: number
example: 0.123
description: request execution time in seconds
required: [execution_time]
health_errors:
type: object
properties:
errors:
description: failed healthcheck execution info
type: array
items:
type: object
properties:
component:
description: component name
type: string
error:
allOf:
- description: healthcheck error
- $ref: '#/components/schemas/Error'
status:
description: component health status
type: integer
enum: [0, 1]
required: [component, error, status]
required: [errors]
example:
errors:
- component: backport3_db
error:
error_code: 10017
desc: Database error
detail: Database connection timeout error
status: 0
- component: api
error:
error_code: 0
desc: Success
detail: Success
status: 1
responses:
internal_server_error:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
server_timeout_error:
description: server timeout error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Error'
example:
error_code: 9
detail: Request timeout
desc: Request timeout on http://127.0.0.1:5140/{...}, method {...}
basic_auth_login_not_found_error:
description: bad request.
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_login:
value:
error_code: 11002
detail: Account corresponding login/password not found
bad_auth_header:
value:
error_code: 36002
detail: |
Bad format basic authorization header, format: Basic base64(login:password)
suspended:
value:
error_code: 11004
detail: Account is suspended
basic_or_token_auth_error:
description: bad request.
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_login:
value:
error_code: 11002
detail: Account corresponding login/password not found
bad_auth_header:
value:
error_code: 36002
detail: |
Bad format basic authorization header, format: Basic base64(login:password)
need_auth_header:
value:
error_code: 12010
detail: This resource needs \"Authorization\" authorization headers
bad_token_format:
value:
error_code: 12001
detail: |
Token is not UUID4, format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
forbidden_resource_error:
description: forbidden
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
forbidden_reourse:
value:
error_code: 12033
detail: Access to this resource on the server is denied
token_not_found:
description: token not found by id
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 11022
detail: Token not found
person_not_found_error:
description: person not found
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 22007
detail: Person with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
descriptor_not_found_error:
description: descriptor not found
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 11018
detail: Descriptor with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
list_not_found_error:
description: list not found
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
face_already_attached_error:
description: face already attached
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 22008
detail: This descriptor is already attached to the person.
face_not_attached_error:
description: faces not found
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 36004
detail: Face was not linked to the person.
object_not_found_error:
description: object not found
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 11020
detail: One or more person not found
forbidden_liveness_error:
description: forbidden, Liveness service is disabled.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 11054
detail: Liveness service is disabled
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: |
This API supports Basic Authentication for access to the account.
Header example: `Authorization: Basic bG9naW46cGFzc3dvcmQ=`
Token:
type: http
scheme: token
description: |
This API supports X-Auth-Token for access to the account.
Header example: `X-Auth-Token: 11c59254-e83f-41a3-b0eb-28fae998f271`
paths:
/4/accounts:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags:
- accounts
summary: create account
description: |
Create a new account with given credentials.
Automatically creates one API token for client authorization. The token is returned within the reply body.
operationId: createAccount
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/application_json_content'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/new_account'
required: true
responses:
201:
description: an account is created.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
properties:
token:
allOf:
- $ref: '#/components/schemas/token'
description: created account token
required:
- token
400:
description: bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_json:
value:
error_code: 12022
detail: 'Failed to validate input json. Path: '''', message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
email_exists:
value:
error_code: 11011
detail: An account with given email already exists
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- accounts
summary: accounts options
description: get options for the resource
operationId: getAccountsOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/account:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
security:
- BasicAuth: []
tags:
- accounts
parameters:
- $ref: '#/components/parameters/luna_request_id'
summary: get account info
description: Get current account registration information and it's status.
operationId: getAccount
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/account'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- accounts
summary: account options
description: get options for the resource
operationId: getAccountOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/account/tokens:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
security:
- BasicAuth: []
tags:
- tokens
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
summary: get account tokens
description: Get all authorization tokens owned by current account. This query is pageable.
operationId: getAccountTokens
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_account_tokens_response'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
post:
security:
- BasicAuth: []
tags:
- tokens
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/application_json_content'
summary: create account token
description: Create an authorization token for current account.
operationId: postAccountTokens
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post_account_tokens_request'
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/post_account_tokens_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'token_data', message: 'token_data must be string'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
delete:
security:
- BasicAuth: []
tags:
- tokens
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/application_json_content'
summary: delete account tokens
description: Delete one or several authorization tokens from current account.
operationId: deleteAccountTokens
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/delete_account_tokens_request'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'tokens[1]', message: 'tokens[1] must match pattern [a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
tags:
- tokens
summary: account tokens options
description: get options for the resource
operationId: getAccountTokensOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/account/tokens/{token_id}:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/token_id_uri'
get:
security:
- BasicAuth: []
tags:
- tokens
summary: get account token
description: Get information about this token.
operationId: getAccountToken
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_account_token_response'
404:
$ref: '#/components/responses/token_not_found'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
tags:
- tokens
parameters:
- $ref: '#/components/parameters/application_json_content'
summary: patch account token
description: Change token data associated with this token.
operationId: patchAccountToken
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patch_account_tokens_request'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'token_data', message: 'token_data must be string'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/token_not_found'
500:
$ref: '#/components/responses/internal_server_error'
delete:
security:
- BasicAuth: []
tags:
- tokens
summary: delete account token
description: Delete this token.
operationId: deleteAccountToken
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/token_not_found'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
tags:
- tokens
summary: account token options
description: get options for the resource
operationId: getAccountTokenOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/token_id_uri'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/descriptors:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- descriptors
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/input_extract_data'
- $ref: '#/components/parameters/estimate_attributes'
- $ref: '#/components/parameters/estimate_emotions'
- $ref: '#/components/parameters/estimate_ethnicities'
- $ref: '#/components/parameters/estimate_quality'
- $ref: '#/components/parameters/score_threshold'
- $ref: '#/components/parameters/warped_image'
- $ref: '#/components/parameters/extract_descriptor'
- $ref: '#/components/parameters/estimate_head_pose'
- $ref: '#/components/parameters/pitch_threshold'
- $ref: '#/components/parameters/yaw_threshold'
- $ref: '#/components/parameters/roll_threshold'
- $ref: '#/components/parameters/extract_exif'
- $ref: '#/components/parameters/no_cache'
summary: create descriptors
description: |
**Extract descriptor(s) from an image**
In order to extract any descriptors, the function performs face detection first. In case of multiple detected faces, the function will produce several descriptors (one per face).
Please note that some faces may not be detected for technical challenges, e.g. very large face angles (head pose) or large occlusion. Frontal and near-frontal faces have the best results.
This function outputs detected faces positions as bounding rectangles. Each rectangle is defined by it's top-left corner position, width and height. Note, that coordinate system origin is at the top-left corner of the image. The face rectangles are stored in *rect* objects per face.
Aside from face detector response, the function also outputs bounding rectangles scaled and biased to resemble conformance to ISO IEC 19794-5 2005(E).
To 'resemble conformance' here means that the standard dictates not only the bounding rectangle shape but also photoshooting conditions. Since Luna is a general system and not a true biometric one, it has no means to guarantee the conditions. However, it can detect person's eyes on a picture and build a rectangle with proportions described in the standard. The best results are observed on non-rotated faces while pose variations introduce errors.
Note, that the procedure of ISO rectangle construction does not take image boundaries into account. The resulting rectangle may outstep the image boundaries. The client is responsible to do proper padding if image cropping is desired.
The ISO face rectangles are stored in *rectISO* objects per face.
Face detection step for arbitrary image is mandatory, and for warped image it will be skipped (see descripton for *warped_image* in the query parameters section below).
All the remaining steps can be enabled or disabled. E.g. while descriptor extraction is enabled by default, the client may disable it provided only face bounding boxes are required. See additional feature descriptions in the query parameters section below.
In order to make face descriptor invariant to some pose variations and scale, each face detection area is cropped from the source image. Then several affine transformations are applied to the crop including rotation and scaling. This process is called warping. Since warping scales all cropped images to the same size, one won't get a much better face descriptor from a higher resolution photograph.
In other way around, while it is possible to extract descriptors from smaller images, matching quality of such descriptors will be lower due to the lack of detail. To give an idea, reasonable face bounding box size is about 150x150 pixels.
It is possible to estimate additional per face attributes, including:
- overall face image quality (suitablity for recognition);
- age;
- gender;
- ethnicities;
- emotions;
- head pose;
These attributes are not stored in the DB.
**Upload an existing descriptor**
To upload an existing descriptor you should set content-type header to *application/x-vl-face-descriptor* for raw descriptor and *application/x-vl-xpk* for xpk-file.
In this case request query parameterss will be ignored. Note, that external descriptors should be extracted with the same descriptor model version as used in the Luna installation.
Otherwise, you won't be able to match them.
> **WARNING** Default descriptor version to extract from image is default descriptor version configured in the system (one of 52, 54, 56, 57, 58). The older descriptor versions are no longer supported.
operationId: createDescriptors
requestBody:
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/x-windows-bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
application/x-vl-face-descriptor:
schema:
type: string
format: binary
application/x-vl-xpk:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-gif-base64:
schema:
type: string
format: byte
image/x-windows-bmp-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
application/x-vl-face-descriptor-base64:
schema:
type: string
format: byte
application/x-vl-xpk-base64:
schema:
type: string
format: byte
required: true
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/extractor_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
low_threshold:
value:
error_code: 36003
detail: No faces found.
bad_content_type:
value:
error_code: 12017
detail: Bad content type
invalid_image_type:
value:
error_code: 100033
detail: ""
bad_warp_image:
value:
error_code: 11043
detail: Bad image size for face warped image
unsupported_descriptor_version:
value:
error_code: 34001
detail: Descriptor version 42 is not supported
bad_sdk_descriptor:
value:
error_code: 12038
detail: SDK descriptor is not valid
bad_xpk:
value:
error_code: 12035
detail: Failed to parse xpk file
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'warped_image'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no_faces:
value:
error_code: 4003
detail: No faces found.
convert_base64:
value:
error_code: 18001
detail: Failed convert data from base64 to bytes
internal_server_error:
value:
error_code: 1
detail: internal server error
get:
security:
- BasicAuth: []
- Token: []
tags:
- descriptors
summary: get descriptors
description: Get info of all descriptors owned by current account.
operationId: getDescriptors
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/descriptors_response'
400:
description: bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'page_size'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- descriptors
summary: descriptors options
description: get options for the resource
operationId: getDescriptorsOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/descriptors/{descriptor_id}:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/descriptor_id_in_path'
get:
security:
- BasicAuth: []
- Token: []
tags:
- descriptors
summary: get descriptor
description: Get descriptor info.
operationId: getDescriptor
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/descriptor_info'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/descriptor_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- descriptors
summary: descriptor options
description: get options for the resource
operationId: getDescriptorOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/descriptors/{descriptor_id}/linked_lists:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/descriptor_id_in_path'
- $ref: '#/components/parameters/luna_request_id'
get:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: get descriptor lists
description: Get all lists that this descriptor is attached to.
operationId: getDescriptorLists
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_descriptor_lists_response'
404:
$ref: '#/components/responses/descriptor_not_found_error'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
parameters:
- $ref: '#/components/parameters/application_json_content'
- $ref: '#/components/parameters/list_id_que_req'
- $ref: '#/components/parameters/do_list'
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: patch descriptor lists
description: |
Attach or detach a descriptor to the list.
Once detached, descriptor's TTL is reset to the default value.
If not attached to a person or to a list, this descriptor will be eventually garbage-collected.
operationId: patchDescriptorLists
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12014
detail: "Required parameters 'list_id' not found"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/descriptor_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: descriptor lists options
description: get options for the resource
operationId: getDescriptorListsOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/portraits/{descriptor_id}:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/descriptor_id_in_path'
get:
security:
- BasicAuth: []
- Token: []
tags:
- portrait
summary: get portrait
description: Get descriptor origin portrait.
operationId: getPortrait
responses:
200:
description: Ok
headers:
Content-Type:
$ref: '#/components/headers/image_content_type'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
image/jpeg:
schema:
type: string
format: binary
example: <binary image>
403:
$ref: '#/components/responses/forbidden_resource_error'
404:
description: portrait not found.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
error_response:
value:
error_code: 13003
detail: "Image with id 'b668c4a5-2191-476e-a261-3b4f9ce2e25e' not found"
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- portrait
summary: portrait options
description: get options for the resource
operationId: getPortraitOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/portraits/{descriptor_id_with_thumbnails}:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/descriptor_id_with_thumbnails_in_path'
get:
security:
- BasicAuth: []
- Token: []
tags:
- portrait
summary: get portrait thumbnails
description: get descriptor portrait thumbnail
operationId: getPortraitThumbnails
responses:
200:
description: Ok
headers:
Content-Type:
$ref: '#/components/headers/image_content_type'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
image/jpeg:
schema:
type: string
format: binary
example: <binary image>
403:
$ref: '#/components/responses/forbidden_resource_error'
404:
description: portrait not found.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
error_response:
value:
error_code: 13003
detail: "Image with id 'b668c4a5-2191-476e-a261-3b4f9ce2e25e' not found"
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- portrait
summary: portrait thumbnails options
description: get options for the resource
operationId: getPortraitThumbnailsOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/persons:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/application_json_content'
summary: create person
description: Create person
operationId: createPerson
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_person'
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
properties:
person_id:
allOf:
- $ref: '#/components/schemas/person_id'
description: created person id
required: [person_id]
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
bad_content_type:
value:
error_code: 12017
detail: Bad content type
bad_json:
value:
error_code: 12022
detail: 'Failed to validate input json. Path: '''', message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
get:
security:
- BasicAuth: []
- Token: []
tags:
- persons
summary: get persons
description: Get persons by filters.
operationId: getPersons
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/user_data'
- $ref: '#/components/parameters/external_id'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
properties:
persons:
$ref: '#/components/schemas/persons'
count:
$ref: '#/components/schemas/person_count'
required: [persons, count]
400:
description: bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'page_size'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- persons
summary: persons options
description: get options for the resource
operationId: getPersonsOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/persons/{person_id}:
parameters:
- $ref: '#/components/parameters/person_id_uri'
get:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
summary: get person
description: Get person
operationId: getPerson
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/person'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
summary: patch person
description: Patch person. Required user data or external id in body
operationId: patchPerson
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_person'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "user_data must be shorter than or equal to 128 characters"
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
delete:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
summary: delete person
description: Delete person
operationId: deletePerson
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- persons
summary: person options
description: get options for the resource
operationId: getPersonOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/persons/{person_id}/linked_descriptors:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/person_id_uri'
get:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
summary: get person descriptors
description: Get person descriptors
operationId: getPersonDescriptors
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
properties:
descriptors:
$ref: '#/components/schemas/person_descriptors'
required: [descriptors]
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- persons
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/descriptor_id'
- $ref: '#/components/parameters/do'
summary: patch person descriptors
description: Attach or detach a descriptor to the person.
operationId: patchPersonDescriptors
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
$ref: '#/components/responses/descriptor_not_found_error'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
404:
$ref: '#/components/responses/person_not_found_error'
409:
$ref: '#/components/responses/face_already_attached_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- persons
summary: person descriptors options
description: get options for the resource
operationId: getPersonDesciptorsOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/persons/{person_id}/linked_lists:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/person_id_uri'
- $ref: '#/components/parameters/luna_request_id'
get:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: get person lists
description: Get all lists that this person is attached to.
operationId: getpersonLists
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_person_lists_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 36001
detail: "Expected list of persons. Got list of descriptors. List id 'c0d05b90-4d83-44bf-b1a6-1d9e5064d218'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
parameters:
- $ref: '#/components/parameters/application_json_content'
- $ref: '#/components/parameters/list_id_que_req'
- $ref: '#/components/parameters/do_list'
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: patch person lists
description: Attach or detach a person to the list.
operationId: patchPersonLists
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12014
detail: "Required parameters 'list_id' not found"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/person_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: person lists options
description: get options for the resource
operationId: getpersonListsOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/lists:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
get:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: get lists
description: Get ids of all lists owned by current account. This query is pageable.
operationId: getLists
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_lists_response'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
post:
security:
- BasicAuth: []
- Token: []
tags:
- lists
parameters:
- $ref: '#/components/parameters/application_json_content'
- $ref: '#/components/parameters/list_type'
summary: create list
description: Create a list.
operationId: postLists
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post_lists_request'
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/post_lists_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'list_data', message: 'list_data must be string'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
delete:
security:
- BasicAuth: []
- Token: []
tags:
- lists
parameters:
- $ref: '#/components/parameters/application_json_content'
summary: delete lists
description: Delete one or multiple lists.
operationId: deleteLists
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/delete_lists_request'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'lists', message: 'lists must be array'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: lists options
description: get options for the resource
operationId: getListsOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/lists/{list_id}:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/list_id_uri'
- $ref: '#/components/parameters/luna_request_id'
get:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: get list
description: Get a list. This query is pageable.
operationId: getList
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/get_list_response'
404:
$ref: '#/components/responses/list_not_found_error'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
parameters:
- $ref: '#/components/parameters/application_json_content'
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: patch a list
description: Patch list data associated with this list.
operationId: patchList
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patch_list_request'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'list_data', message: 'token_data must be string'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/list_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
delete:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: delete list
description: Delete a list.
operationId: deleteList
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
404:
$ref: '#/components/responses/list_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: list options
description: get options for the resource
operationId: getListOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
/4/storage/linker:
parameters:
- $ref: '#/components/parameters/cors_origin'
- $ref: '#/components/parameters/luna_request_id'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: linker
description: Attach or detach several descriptors or persons to list.
operationId: patchLinker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patch_linker_request'
responses:
204:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error_code: 12022
detail: "Failed to validate input json. Path: 'list_id', message: 'list_id must be string'"
401:
$ref: '#/components/responses/basic_auth_login_not_found_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
security:
- BasicAuth: []
- Token: []
tags:
- lists
summary: linker options
description: get options for the resource
operationId: getLinkerOptions
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/matching/verify:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags:
- matching
summary: verification
security:
- BasicAuth: []
- Token: []
description: |
Verification is done via matching a reference descriptor with a set of candidate descriptors belonging to a
single person.
The reference descriptor should be specified explicitly. The set of candidate descriptors consists of all
descriptors attached to the verified person.
operationId: matchingVerify
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/verify_descriptor_id'
- $ref: '#/components/parameters/verify_person_id'
responses:
201:
description: Create success.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/verify_schemas'
400:
description: Bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
person_not_found:
value:
error_code: 22007
detail: Person with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
descriptor_not_found:
value:
error_code: 11018
detail: Descriptor with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- matching
summary: verify options
description: get options for the resource
operationId: getVerifyOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/matching/identify:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags:
- matching
summary: identification
security:
- BasicAuth: []
- Token: []
description: |
Identification is done via matching a reference descriptor with a list of candidate persons' descriptors.
The reference descriptor may be specified explicitly or taken from a person defined by the person ID.
The matching process produces similarities for each candidate. Maximum of top 5 most similar results are
then selected. Identification result is a short list of the most similar persons and their
similarity scores. It's up to the user to decide whether the similarity score is high enough to consider it a
successful match or not.
Person ID or a descriptor ID can be set as a reference for matching. An ID of persons list or the set of persons
IDs can be specified as candidates for matching.
Only one of `descriptor_id` or `person_id` query parameters should be specified as the reference at a time. You can not
set both at once.
Only one of `list_id` or `persons_ids` should be specified as the candidate.
If you specify several parameters, the service will choose only one of them.
operationId: matchingIdentify
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/reference_person_id'
- $ref: '#/components/parameters/reference_descriptor_id'
- $ref: '#/components/parameters/candidates_list_id'
- $ref: '#/components/parameters/candidates_person_ids'
- $ref: '#/components/parameters/limit'
responses:
201:
description: Create success.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/match_by_persons_schema'
400:
description: Bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
person_not_found:
value:
error_code: 22007
detail: Person with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
descriptor_not_found:
value:
error_code: 11018
detail: Descriptor with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'limit'
object_not_found:
value:
error_code: 11020
detail: One or more person not found
list_not_found:
value:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
params_not_found:
value:
error_code: 12016
detail: Bad/incomplete input data", "No one parameters '[person_id, descriptor_id]' not found
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- matching
summary: identify options
description: get options for the resource
operationId: getIdentifyOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/matching/match:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags:
- matching
summary: raw match
security:
- BasicAuth: []
- Token: []
description: |
Matching person or descriptor by descriptors. Descriptors can be represent as a ID of descriptors list or
a descriptor ID set.
Only one of `descriptor_id` or `person_id` query parameters should be specified as the reference at a time. You can not
set both at once. Also only one of `list_id` or `descriptor_ids` should be specified as the candidate.
If you specify several parameters service will choose one of them.
operationId: matchingMatch
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/reference_person_id'
- $ref: '#/components/parameters/reference_descriptor_id'
- $ref: '#/components/parameters/candidates_list_id'
- $ref: '#/components/parameters/candidates_descriptor_ids'
- $ref: '#/components/parameters/limit'
responses:
201:
description: Create success.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/match_by_descriptors_schema'
400:
description: Bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
person_not_found:
value:
error_code: 22007
detail: Person with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
descriptor_not_found:
value:
error_code: 11018
detail: Descriptor with id '557d54ec-29ad-4f3c-93b4-c9092ef12515' not found.
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'limit'
object_not_found:
value:
error_code: 11020
detail: One or more descriptor not found
list_not_found:
value:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
params_not_found:
value:
error_code: 12016
detail: Bad/incomplete input data", "No one parameters '[person_id, descriptor_id]' not found
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- matching
summary: match options
description: get options for the resource
operationId: getMatchOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/matching/search:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags:
- matching
summary: search
security:
- BasicAuth: []
- Token: []
description: |
Search a person by photo. This request is just a simple way to tell "extract a descriptor then match it with a
list ". This request is equivalent to POST'ing to /descriptors then to /matching/identify or /matching/match.
Search request requires the input photo to contain only one face.
Only one of `list_id` or `descriptor_ids`, `person_ids` query parameters should be specified
as the candidate at a time. If you specify several parameters service will choose one of them.
operationId: matchingSearch
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/candidates_list_id'
- $ref: '#/components/parameters/candidates_descriptor_ids'
- $ref: '#/components/parameters/candidates_person_ids'
- $ref: '#/components/parameters/input_extract_data'
- $ref: '#/components/parameters/estimate_attributes'
- $ref: '#/components/parameters/estimate_emotions'
- $ref: '#/components/parameters/estimate_ethnicities'
- $ref: '#/components/parameters/estimate_quality'
- $ref: '#/components/parameters/score_threshold'
- $ref: '#/components/parameters/warped_image'
- $ref: '#/components/parameters/estimate_head_pose'
- $ref: '#/components/parameters/pitch_threshold'
- $ref: '#/components/parameters/yaw_threshold'
- $ref: '#/components/parameters/roll_threshold'
- $ref: '#/components/parameters/extract_exif'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/no_cache'
requestBody:
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/x-windows-bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
application/x-vl-face-descriptor:
schema:
type: string
format: binary
application/x-vl-xpk:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-gif-base64:
schema:
type: string
format: byte
image/x-windows-bmp-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
application/x-vl-face-descriptor-base64:
schema:
type: string
format: byte
application/x-vl-xpk-base64:
schema:
type: string
format: byte
required: true
responses:
201:
description: Create success.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/search_schema'
examples:
by_persons:
value:
face:
id: 68bc0e39-af0a-4212-a36a-e17562437e5c
score: 0.8056654334000001
rect:
x: 501
'y': 88
width: 403
height: 529
rectISO:
height: 896
width: 672
x: 321
'y': -159
candidates:
- person_id: 82ac503b-5856-4531-abac-9f06be00923c
user_data: user data
external_id: external-id3
similarity: 0.9975399971000001
descriptor_id: 2868b980-d2bb-49eb-bb5d-5eeb4cad4171
- person_id: a3a56bac-c11c-4fb8-afac-a50a6d4e4781
user_data: ""
external_id: external-id2
similarity: 0.9945
descriptor_id: 6b14a2ac-3d45-4d65-9401-7c5ec0725048
- person_id: 37c035d6-032c-453d-804c-e85dbaf83126
user_data: test user data
external_id: external-id1
similarity: 0.9840
descriptor_id: 9733f323-a490-4436-86c5-77101cfea0d4
by_descriptors:
value:
face:
id: e94e2a54-047d-4063-a9bc-0e6a3ae57162
score: 0.8056654334000001
rect:
x: 501
'y': 88
width: 403
height: 529
rectISO:
height: 896
width: 672
x: 321
'y': -159
candidates:
- id: 81f4d605-871d-4b14-b6b8-9127b0aa6603
similarity: 0.9975399971000001
- id: 5f84111f-a7b6-43e9-b654-9a932787206c
similarity: 0.9945045114000001
- id: 2f9d5eec-7561-40ba-9a5e-522967c304ed
similarity: 0.9840258956000001
400:
description: Bad request.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/many_faces_error'
examples:
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'limit'
object_not_found:
value:
error_code: 11020
detail: One or more descriptor not found
list_not_found:
value:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
low_threshold:
value:
error_code: 36003
detail: No faces found.
bad_content_type:
value:
error_code: 12017
detail: Bad content type
invalid_image_type:
value:
error_code: 100033
detail: ""
unsupported_param:
value:
error_code: 36012
detail: Unsupported param 'extract_descriptor'
many_faces:
value:
error_code: 11012
detail:
faces:
[
{
"id": "ed6b15f9-786c-46b9-bfbb-8f4cea096169",
"score": 0.7672638893,
"rect": {"x": 1729, "y": 196, "width": 72, "height": 97},
"rectISO": {"height": 181, "width": 136, "x": 1704, "y": 157}
},
{
"id": "ad69199e-dc53-458c-b71c-a9a84f9f1740",
"score": 0.7683178782000001,
"rect": {"x": 1393, "y": 239, "width": 73, "height": 95},
"rectISO": {"height": 176, "width": 132, "x": 1369, "y": 202}},
]
params_not_found:
value:
error_code: 12016
detail: Bad/incomplete input data", "No one parameters '[list_id, person_ids, descriptor_id]' not found
unsupported_descriptor_version:
value:
error_code: 34001
detail: Descriptor version 42 is not supported
bad_sdk_descriptor:
value:
error_code: 12038
detail: SDK descriptor is not valid
bad_xpk:
value:
error_code: 12035
detail: Failed to parse xpk file
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no_faces:
value:
error_code: 4003
detail: No faces found.
convert_base64:
value:
error_code: 18001
detail: Failed convert data from base64 to bytes
internal_server_error:
value:
error_code: 1
detail: internal server error
options:
tags:
- matching
summary: search options
description: get options for the resource
operationId: getSearchOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/liveness:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
tags: [liveness]
security:
- BasicAuth: []
- Token: []
summary: predict liveness
description: |
Predict liveness probability in input images.
The response contains the probability that there is a real person in the image, and it is not a presentation attack.
Liveness V1 or Liveness V2 can be used for this resource. Liveness V2 does not use "meta" section of the request.
The incoming images should correspond the requirements of the utilized Liveness. See "Administrator’s manual" for details.
*Liveness estimation is not supported for samples (warped images).*
operationId: predictLiveness
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/multiple_images_content_type'
- $ref: '#/components/parameters/aggregate_liveness'
x-code-samples:
- lang: 'bash'
source: |
curl -H "Authorization: Basic aG9ybnNhbmRob292ZXNAdmwucnU6c2VjcmV0cGFzc3dvcmQ=" \
--form "image=@image.jpg;type=image/jpeg" \
--form "meta={\"OS\":\"DESKTOP\"};type=application/json" \
http://127.0.0.1:5140/4/liveness
- lang: python
source: |
import requests
import json
files = {"meta": ("meta", json.dumps({"OS": "IOS"}), "application/json"),
"image": ("image.jpg", open("image.jpg", "rb"), "image/jpeg")}
auth = {"Authorization": "Basic aG9ybnNhbmRob292ZXNAdmwucnU6c2VjcmV0cGFzc3dvcmQ="}
url = "http://127.0.0.1:5140/4/liveness"
response = requests.post(url, files=files, headers=auth)
requestBody:
content:
multipart/form-data:
schema:
type: object
description: filename in the header of the subpart (content-disposition header) MUST be supplied.
properties:
meta:
$ref: '#/components/schemas/LivenessMeta'
x_meta:
type: object
description: The JSON string with any additional information
image:
$ref: '#/components/schemas/image_list_for_multipart'
required: [image]
application/json:
schema:
type: object
properties:
meta:
$ref: '#/components/schemas/LivenessMeta'
x_meta:
type: object
description: The JSON string with any additional information
urls:
$ref: '#/components/schemas/ListOfUrlsWithImages'
required: [urls]
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
required: true
responses:
200:
description: Success
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/liveness_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_query:
value:
error_code: 12012
desc: Bad/incomplete input data
bad_content_type:
value:
error_code: 12017
desc: Bad/incomplete input data
bad_conten_type_download_image:
value:
error_code: 11028
desc: Bad/incomplete input data
bad_conten_type_multepart:
value:
error_code: 11029
desc: Bad/incomplete input data
failed_load_image:
value:
error_code: 11027
desc: External request failed
bad_multipart_body:
value:
error_code: 11049
desc: Bad/incomplete input data
403:
$ref: '#/components/responses/forbidden_liveness_error'
500:
$ref: '#/components/responses/internal_server_error'
/4/handlers/extractor:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/input_extract_data'
- in: query
name: user_data
schema:
$ref: '#/components/schemas/user_data'
required: false
description: User-defined data. Arbitrary string.
- in: query
name: external_id
schema:
$ref: '#/components/schemas/person_external_id'
required: false
description: External id of the person.
- $ref: '#/components/parameters/warped_image'
- $ref: '#/components/parameters/no_cache'
summary: face extractor
description: |
Extract a descriptor from an image or save input descrptor, create person with this descriptor, attach person
to a predefined list.
If the image contains several faces, the best one (in terms of score) will be used.
Input images can be filtered according to predefined thresholds (quality threshold and head angles).
The resulting fields of the created face object differ depending on the handler configuration.
operationId: extractFace
requestBody:
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/x-windows-bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
application/x-vl-face-descriptor:
schema:
type: string
format: binary
application/x-vl-xpk:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-gif-base64:
schema:
type: string
format: byte
image/x-windows-bmp-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
application/x-vl-face-descriptor-base64:
schema:
type: string
format: byte
application/x-vl-xpk-base64:
schema:
type: string
format: byte
required: true
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
required: ["person_id", "face"]
properties:
person_id:
$ref: '#/components/schemas/person_id'
face:
oneOf:
- $ref: '#/components/schemas/extracted_face'
- $ref: '#/components/schemas/extracted_face_warp'
- $ref: '#/components/schemas/extracted_face_raw_data'
exif:
$ref: '#/components/schemas/exif'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
low_threshold:
value:
error_code: 36003
detail: No faces found.
bad_content_type:
value:
error_code: 12017
detail: Bad content type
invalid_image_type:
value:
error_code: 100033
detail: ""
bad_warp_image:
value:
error_code: 11043
detail: Bad image size for face warped image
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'warped_image'
unsupported_descriptor_version:
value:
error_code: 34001
detail: Descriptor version 42 is not supported
bad_sdk_descriptor:
value:
error_code: 12038
detail: SDK descriptor is not valid
bad_xpk:
value:
error_code: 12035
detail: Failed to parse xpk file
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no_faces:
value:
error_code: 36005
detail: No faces found.
convert_base64:
value:
error_code: 18001
detail: Failed convert data from base64 to bytes
internal_server_error:
value:
error_code: 1
detail: internal server error
get:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: get extractor handler
description: The request enables you to get the parameters specified for the extractor handler.
operationId: getHandlerExtractor
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/extractor_handler_response'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: patch extractor handler
description: |
The request enables you to update the extractor handler parameters. You should specify at least one parameters in the request.
operationId: patchHandlerExtractor
parameters:
- $ref: '#/components/parameters/luna_request_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/extractor_handler_policies_request'
required: true
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/patch_handler_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_content_type:
value:
error_code: 12017
detail: Bad content type
bad_json:
value:
error_code: 12022
detail: 'Failed to validate input json. Path: '''', message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
list_not_found:
value:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- handlers
summary: extractor options
description: get options for the resource
operationId: getFaceExtractorOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/handlers/verify:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/input_extract_data'
- $ref: '#/components/parameters/warped_image'
- in: query
name: person_id
schema:
$ref: '#/components/schemas/person_id'
required: true
description: person ID
- $ref: '#/components/parameters/no_cache'
summary: verify face
description: |
Extract a descriptor from an image or save input descrptor, then match it to a person.
If the image contains several faces, the best one (in terms of score) will be used.
The resulting fields of the created face object differ depending on the handler configuration.
operationId: verifyFace
requestBody:
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/x-windows-bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
application/x-vl-face-descriptor:
schema:
type: string
format: binary
application/x-vl-xpk:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-gif-base64:
schema:
type: string
format: byte
image/x-windows-bmp-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
application/x-vl-face-descriptor-base64:
schema:
type: string
format: byte
application/x-vl-xpk-base64:
schema:
type: string
format: byte
required: true
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/handler_verification_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
low_threshold:
value:
error_code: 36003
detail: No faces found.
bad_content_type:
value:
error_code: 12017
detail: Bad content type
invalid_image_type:
value:
error_code: 100033
detail: ""
bad_warp_image:
value:
error_code: 11043
detail: Bad image size for face warped image
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'warped_image'
unsupported_descriptor_version:
value:
error_code: 34001
detail: Descriptor version 42 is not supported
bad_sdk_descriptor:
value:
error_code: 12038
detail: SDK descriptor is not valid
bad_xpk:
value:
error_code: 12035
detail: Failed to parse xpk file
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no_faces:
value:
error_code: 36005
detail: No faces found.
convert_base64:
value:
error_code: 18001
detail: Failed convert data from base64 to bytes
internal_server_error:
value:
error_code: 1
detail: internal server error
get:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: get verify handler
description: The request enables you to get the parameters specified for the verify handler.
operationId: getHandlerVerify
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/verify_handler_response'
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: patch verify handler
description: |
The request enables you to update the verify handler parameters. You should specify at least one parameters in the request.
operationId: patchHandlerVerify
parameters:
- $ref: '#/components/parameters/luna_request_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/verify_handler_policies_request'
required: true
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/patch_handler_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_content_type:
value:
error_code: 12017
detail: Bad content type
bad_json:
value:
error_code: 12022
detail: 'Failed to validate input json. Path: '''', message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- handlers
summary: verify options
description: get options for the resource
operationId: getFaceVerifyOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/handlers/verify/raw:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: batch verification
description: |
Raw API allows to do similarity and verification status calculations for input descriptors.
operationId: rawBatchVerification
parameters:
- $ref: '#/components/parameters/json_or_msgpack_content'
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/no_cache'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/raw_batch_verification_request_json'
application/msgpack:
schema:
$ref: '#/components/schemas/raw_batch_verification_request_msgpack'
required: true
responses:
200:
description: Ok
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/raw_batch_verification_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_content_type:
value:
error_code: 12017
desc: Bad/incomplete input data
detail: Bad content type
bad_json:
value:
error_code: 12022
desc: Bad/incomplete input data
detail: 'Failed to validate input json. Path: ''candidates'', message: ''candidates[0] must be valid exactly by one of oneOf definition'''
bad_base64_for_one_descriptor:
value:
error_code: 18001
desc: Bad/incomplete input data
detail: Failed convert data from base64 to bytes
wrong_descriptors_length:
value:
error_code: 12034
desc: Bad/incomplete input data
detail: Descriptor has incorrect length 200
bad_xpk_file:
value:
error_code: 12035
desc: Bad/incomplete input data
detail: Failed to parse xpk file
bad_sdk_descripot:
value:
error_code: 12038
desc: Bad/incomplete input data
detail: SDK descriptor is not valid
xpk_does_not_contain_descriptor:
value:
error_code: 12037
desc: Bad/incomplete input data
detail: XPK file does not contain descriptor
unknown_descriptor_version:
value:
error_code: 12037
desc: Bad/incomplete input data
detail: Descriptor version 37 are not registered in the system
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- handlers
summary: raw batch verification options
description: get options for the resource
operationId: rawBatchVerificationOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/handlers/identify:
parameters:
- $ref: '#/components/parameters/cors_origin'
post:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/input_extract_data'
- $ref: '#/components/parameters/warped_image'
- $ref: '#/components/parameters/no_cache'
summary: identify face
description: |
Extract a descriptor from an image or save input descrptor, then match it to a predefined list of candidates.
If the image contains several faces, the best one (in terms of score) will be used.
The resulting fields of the created face object differ depending on the handler configuration.
operationId: identifyFace
requestBody:
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/x-windows-bmp:
schema:
type: string
format: binary
image/x-portable-pixmap:
schema:
type: string
format: binary
application/x-vl-face-descriptor:
schema:
type: string
format: binary
application/x-vl-xpk:
schema:
type: string
format: binary
image/x-jpeg-base64:
schema:
type: string
format: byte
image/x-png-base64:
schema:
type: string
format: byte
image/x-bmp-base64:
schema:
type: string
format: byte
image/x-tiff-base64:
schema:
type: string
format: byte
image/x-gif-base64:
schema:
type: string
format: byte
image/x-windows-bmp-base64:
schema:
type: string
format: byte
image/x-portable-pixmap-base64:
schema:
type: string
format: byte
application/x-vl-face-descriptor-base64:
schema:
type: string
format: byte
application/x-vl-xpk-base64:
schema:
type: string
format: byte
required: true
responses:
201:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
required: ["candidates", "face"]
properties:
candidates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/match_vs_person'
- $ref: '#/components/schemas/match_vs_descriptor'
face:
oneOf:
- $ref: '#/components/schemas/extracted_face'
- $ref: '#/components/schemas/extracted_face_warp'
- $ref: '#/components/schemas/extracted_face_raw_data'
exif:
$ref: '#/components/schemas/exif'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
low_threshold:
value:
error_code: 36003
detail: No faces found.
bad_content_type:
value:
error_code: 12017
detail: Bad content type
invalid_image_type:
value:
error_code: 100033
detail: ""
bad_warp_image:
value:
error_code: 11043
detail: Bad image size for face warped image
bad_query_param:
value:
error_code: 12012
detail: Bad query parameters 'warped_image'
unsupported_descriptor_version:
value:
error_code: 34001
detail: Descriptor version 42 is not supported
bad_sdk_descriptor:
value:
error_code: 12038
detail: SDK descriptor is not valid
bad_xpk:
value:
error_code: 12035
detail: Failed to parse xpk file
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
description: internal server error.
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no_faces:
value:
error_code: 4003
detail: No faces found.
convert_base64:
value:
error_code: 18001
detail: Failed convert data from base64 to bytes
internal_server_error:
value:
error_code: 1
detail: internal server error
get:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: get identify handler
description: The request enables you to get the parameters specified for the identify handler.
operationId: getHandlerIdentify
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/identify_handler_response'
500:
$ref: '#/components/responses/internal_server_error'
patch:
security:
- BasicAuth: []
- Token: []
tags:
- handlers
summary: patch identify handler
description: |
The request enables you to update the identify handler parameters.
You should specify at least one parameters in the request.
operationId: patchHandlerIdentify
parameters:
- $ref: '#/components/parameters/luna_request_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/identify_handler_policies_request'
required: true
responses:
200:
description: OK
headers:
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Content-Type:
$ref: '#/components/headers/application_json'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/patch_handler_response'
400:
description: Bad request
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
bad_content_type:
value:
error_code: 12017
detail: Bad content type
bad_json:
value:
error_code: 12022
detail: 'Failed to validate input json. Path: '''', message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
list_not_found:
value:
error_code: 22003
detail: List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
401:
$ref: '#/components/responses/basic_or_token_auth_error'
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- handlers
summary: identify options
description: get options for the resource
operationId: getFaceIdentifyOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/4/docs/spec:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
tags:
- documents
summary: get openapi documentation
description: |
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`
operationId: getSpec
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/accept_docs_handler'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/docs_content_type'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/x-yaml:
schema:
type: string
description: yaml format documentation
text/html:
schema:
type: string
description: html format documentation
415:
description: Unsupported Media Type
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unsupported_media_type:
value:
error_code: 12024
detail: 'Bad/incomplete input data'
desc: "Unsupported media type"
500:
$ref: '#/components/responses/internal_server_error'
/4/docs/dev:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
tags:
- documents
summary: get development manual
description: |
Get sphinx documentation - *Development Manual*. After the request you will be redirected to the page `/docs/dev/index.html`
operationId: getDevManual
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/text_html'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
text/html:
schema:
type: string
description: html format documentation
500:
$ref: '#/components/responses/internal_server_error'
/4/config:
get:
tags:
- config
summary: get service configuration
description: Get service configuration. Passwords and tokens will be hidden in the response.
operationId: getConfig
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/accept_config_handler'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/config_accept_content_type'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
type: object
description: json format configuration
example:
INFLUX_MONITORING:
SEND_DATA_FOR_MONITORING: 0
VERSION: 2
ORGANIZATION: ORGANIZATION_NAME
TOKEN: '********'
BUCKET: luna_monitoring
HOST: 127.0.0.1
PORT: 8086
USE_SSL: 0
FLUSHING_PERIOD: 1.0
text/plain:
schema:
type: string
description: text format configuration
example: |
[INFLUX_MONITORING]
SEND_DATA_FOR_MONITORING = 0
VERSION = 2
ORGANIZATION = ORGANIZATION_NAME
TOKEN = ********
BUCKET = luna_monitoring
HOST = 127.0.0.1
PORT = 8086
USE_SSL = 0
FLUSHING_PERIOD = 1.0
415:
description: Unsupported Media Type
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unsupported_media_type:
value:
error_code: 12024
desc: "Unsupported media type"
500:
$ref: '#/components/responses/internal_server_error'
/4/healthcheck:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
tags:
- health
summary: get health
description: get health of service
operationId: healthcheck
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/include_luna_services'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
$ref: '#/components/schemas/health_ok'
500:
$ref: '#/components/responses/internal_server_error'
502:
description: Unhealthy
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
$ref: '#/components/schemas/health_errors'
504:
$ref: '#/components/responses/server_timeout_error'
options:
tags:
- health
summary: health options
description: get options for the resource
operationId: getHealthOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'
/healthcheck:
get:
tags:
- health
summary: get health (redirect)
description: get health of service (redirect)
operationId: healthcheck(redirect)
parameters:
- $ref: '#/components/parameters/luna_request_id'
- $ref: '#/components/parameters/include_luna_services'
responses:
200:
description: OK (redirected)
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
$ref: '#/components/schemas/health_ok'
308:
description: Moved permanently
headers:
Location:
schema:
type: string
enum:
- "/6/healthcheck"
required: true
description: redurect to the versioned resource
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
500:
$ref: '#/components/responses/internal_server_error'
502:
description: Unhealthy (redirected)
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
content:
application/json:
schema:
$ref: '#/components/schemas/health_errors'
504:
$ref: '#/components/responses/server_timeout_error'
/version:
parameters:
- $ref: '#/components/parameters/cors_origin'
get:
tags:
- version
summary: get version
description: get versions of services
operationId: getVersion
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
content:
application/json:
schema:
type: object
properties:
Version:
type: object
properties:
luna_api:
$ref: '#/components/schemas/version'
luna_handlers:
$ref: '#/components/schemas/version'
luna_faces:
$ref: '#/components/schemas/version'
luna_image_store_faces_samples:
$ref: '#/components/schemas/version'
luna_image_store_bodies_samples:
$ref: '#/components/schemas/version'
luna_image_store_images:
$ref: '#/components/schemas/version'
luna_events:
$ref: '#/components/schemas/version'
luna_tasks:
$ref: '#/components/schemas/version'
luna_python_matcher:
$ref: '#/components/schemas/version'
luna_matcher_proxy:
$ref: '#/components/schemas/version'
LUNA PLATFORM:
$ref: '#/components/schemas/base_version_schema'
luna_backport3:
$ref: '#/components/schemas/version'
required: [luna_api, luna_handlers, luna_faces, luna_image_store_faces_samples,
luna_image_store_bodies_samples, luna_image_store_images, LUNA PLATFORM, luna_backport3]
required: [Version]
example:
Version:
luna_api:
api: 5
major: 3
minor: 1
patch: 2
luna_handlers:
api: 1
major: 1
minor: 0
patch: 0
luna_faces:
api: 2
major: 2
minor: 3
patch: 9
luna_image_store_faces_samples:
api: 1
major: 2
minor: 1
patch: 10
luna_image_store_bodies_samples:
api: 1
major: 2
minor: 1
patch: 11
luna_image_store_images:
api: 1
major: 2
minor: 1
patch: 13
luna_events:
api: 1
major: 1
minor: 0
patch: 5
luna_tasks:
api: 1
major: 1
minor: 0
patch: 13
luna_python_matcher:
api: 1
major: 0
minor: 0
patch: 6
LUNA PLATFORM:
major: 0
minor: 0
patch: 0
luna_backport3:
api: 1
major: 0
minor: 0
patch: 1
500:
$ref: '#/components/responses/internal_server_error'
options:
tags:
- version
summary: version options
description: get options for the resource
operationId: getVersionOptions
parameters:
- $ref: '#/components/parameters/luna_request_id'
responses:
200:
description: OK
headers:
Content-Type:
$ref: '#/components/headers/application_json'
Luna-Request-Id:
$ref: '#/components/headers/luna_request_id'
Allow:
$ref: '#/components/headers/allow_methods'
Access-Control-Allow-Origin:
$ref: '#/components/headers/access_control_allow_origin'
Access-Control-Allow-Headers:
$ref: '#/components/headers/access_control_allow_headers'
Access-Control-Allow-Methods:
$ref: '#/components/headers/access_control_allow_methods'
Access-Control-Max-Age:
$ref: '#/components/headers/access_control_max_age'
500:
$ref: '#/components/responses/internal_server_error'