Recognize


Данный метод позволяет распознать person по заданной фотографии. В случае, если совпадение не найдено, будет добавлен новый person.

Запрос

Авторизационные данные передаются в строке запроса:

Параметр

Тип

Значение

oauth_token

string

OAuth2 access token (required non-empty)

oauth_provider

string

провайдер OAuth2 (required non-empty)


Поддерживаемые провайдеры OAuth2:

Провайдер

Значение oauth_provider

Получение токена

Mail.Ru

mr

https://help.mail.ru/biz/vision/api/v1/oauth_token

MCS
mcs https://mcs.mail.ru/help/vision-auth/vision-token (все клиенты MCS)


Параметры запроса передаются в формате JSON в теле запроса с name="meta":

Параметр

Тип

По умолчанию

Значение

space

string

--

числовой идентификатор, используемый для избежания пересечений по персонам (required non-empty)

create_new

bool

false

добавлять ли новый person, если не было найдено совпадений

images

[]image_meta

--

метаданные передаваемых изображений (required non-empty)


Параметр space используется для избежания пересечений по person. Таким образом, person1 из space 0 и person1 из space 1 разные. Для приложений, решающих различные задачи, имеет смысл использовать различные значения space.

Клиент может иметь до 10 различных space, значения space изменяются от "0" до "9". В случае превышения лимита вернется ошибка.

image_meta

Параметр

Тип

Значение

name

string

имена файлов для сопоставления файлов в запросе и ответе (required non-empty)


Изображения передаются в теле запроса, значения поля name должны соответствовать переданным в images. Максимальное количество изображений в одном запросе равняется 100. Максимальный размер каждого изображения не должен превышать 4МБ.

Пример запроса:

POST /api/v1/persons/recognize?oauth_provider=mr&oauth_token=123 HTTP/1.1

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryfCqTBHeLZlsicvMp
  
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="file_0"; filename=""
Content-Type: image/jpeg

000000000000000000000000000
000000000000000000000000000
000000000000000000000000000
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="file_1"; filename=""
Content-Type: image/jpeg
  
111111111111111111111111111
111111111111111111111111111
111111111111111111111111111
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="file_2"; filename=""
Content-Type: image/jpeg

222222222222222222222222222
222222222222222222222222222
222222222222222222222222222
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="file_3"; filename=""
Content-Type: image/jpeg

333333333333333333333333333
333333333333333333333333333
333333333333333333333333333
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="file_4"; filename=""
Content-Type: image/jpeg

444444444444444444444444444
444444444444444444444444444
444444444444444444444444444
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="meta"
  
{"space":"0", "images":[{"name":"file_0"},{"name":"file_1"},{"name":"file_2"},{"name":"file_3"},{"name":"file_4"}]}
------WebKitFormBoundaryfCqTBHeLZlsicvMp--

Ответ

Параметр

Тип

Значение

status

int

200 в случае успеха, иначе описание ошибки будет в body

body

string | response

тело ответа

response

Параметр

Тип

Значение

objects

[]object

массив ответов для каждого файла

aliases_changed

bool

изменились ли алиасы

object

Параметр

Тип

Значение

status

enum

результат выполнения

error

string

текстовое описание ошибки (optional)

name

string

имя файла для сопоставления файлов в запросе и ответе

persons

[]person

массив персон, найденных на фото (optional)

status

Параметр

Значение

0

успешно

1

перманентная ошибка

2

временная ошибка

person

Параметр

Тип

Значение

tag

string

идентификатор найденной персоны

coord

[]int

координаты найденного лица [left x, top y, right x, bottom y]

aliases

[]string

массив похожих персон (optional)

confidence

float

степень уверенности детектора лиц в том, что найденное изображение является лицом (от 0 до 1)

similarity

float

степень похожести найденного лица с персоной в базе

awesomeness

float

условная "крутость" фотографии (от 0 до 1)


Только для второй модели:

Параметр

Тип

Значение

sex

string

пол персоны ["female", "male"]

age

float

возраст персоны

emotion

string

эмоции персоны  

"Neutral", "Happiness", "Sadness", "Surprise", "Fear", "Disgust", "Anger", "Contempt"

valence

float

уровень одобрения человеком ситуации, в которой он находится [-1;1]

arousal

float

уровень вовлеченности человека [-1 - сонный, не активный человек; 1 - активный человек]


Значение tag может равняться "undefined" в случае, если значение create_new  в запросе равнялось false, и по предоставленному изображению в базе не был найден соответствующий person.


Пример ответа:

{
   "status":200,
   "body":{
      "objects":[
         {
            "status":0,
            "name":"file_0"
         },
         {
            "status":1,
            "name":"file_1",
            "error":"The memory contains data of an unknown image type"
         },
         {
            "status":0,
            "name":"file_2",
            "persons":[
               {
                  "tag":"person9",
                  "coord":[149,60,234,181],
                  "confidence":0.9999,
                  "similarity":0.9987,
                  "awesomeness":0.45,
                            "sex":"female",
                            "emotion":"Sadness",
                            "age":30.0,
                            "valence":-0.6184,
                          "arousal":-0.0578
               },
               {
                  "tag":"person10",
                  "coord":[159,70,224,171],
                  "confidence":0.9998,
                  "similarity":0.9987,
                  "awesomeness":0.32,
                "sex":"male",
                "emotion":"Sadness",
                "age":22.0,
                "valence":-0.8184,
                "arousal":-0.0578
               }
            ]
         },
         {
            "status":0,
            "name":"file_3",
            "persons":[
               {
                  "tag":"person11",
                  "coord":[157,60,232,111],
                  "aliases":["person12", "person13"],
                  "confidence":0.9998,
                  "similarity":0.9987,
                  "awesomeness":0.32,
                "sex":"female",
                "emotion":"Sadness",
                "age":12.0,
                "valence":-0.8184,
                "arousal":-0.0578
               }
            ]
         },
         {
            "status":0,
            "name":"file_4",
            "persons":[
               {
                  "tag":"undefined",
                  "coord":[147,50,222,121],
                  "confidence":0.9997,
                  "similarity":0.9987,
                  "awesomeness":0.26,
                "sex":"male",
                "emotion":"Sadness",
                "age":27.0,
                "valence":0.3184,
                "arousal":0.1518
               }
            ]
         }
      ],
      "aliases_changed":false
   },
   "htmlencoded":false,
   "last_modified":0
}