VK Cloud logo

Распознавание лиц

HOST: https://smarty.mail.ru

Для распознавания лиц используются четыре метода API:

  • Set (/api/v1/persons/set)
  • Recognize (/api/v1/persons/recognize)
  • Delete (/api/v1/persons/delete)
  • Truncate (/api/v1/persons/truncate)

Рассмотрим каждый из них подробнее.

Set

Данный метод позволяет установить связь между заданной фотографией и конкретным person_id.

Запрос

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

ПараметрТипЗначение
oauth_token
string
 OAuth2 access token (required non-empty)
oauth_provider
string
Провайдер OAuth2 (required non-empty)

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

ПровайдерЗначение oauth_providerПолучение токена
Mail.Ru
mcs
Смотрите в статье

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

ПараметрТипЗначение
space
string
Имена файлов для сопоставления файлов в запросе и ответе (required non-empty)
images
[]image_meta
ID, сопоставляемый персоне на фото (required non-empty)

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

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

image_meta

ПараметрТипЗначение
name
string
Имена файлов для сопоставления файлов в запросе и ответе (required non-empty
person_id
int
ID, сопоставляемый персоне на фото (required non-empty)

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

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

POST /api/v1/persons/set?oauth_provider=mcs&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="meta"

{"space":"0", "images":[{"name":"file_0", "person_id":1},{"name":"file_1", "person_id":2}]}
------WebKitFormBoundaryfCqTBHeLZlsicvMp--

Ответ

ПараметрТипЗначение
status
int
200 в случае успешного взаимодействия с серверами Vision
body
response
Тело ответа

response

ПараметрТипЗначение
objects
[]object
массив ответов для каждого файла

object

ПараметрТипЗначение
status
enum
Результат выполнения
error
string
Текстовое описание ошибки (optional)
name
string
Имя файла для сопоставления файлов в запросе и ответе

status

ПараметрЗначение
0
Успешно
1
Массив найденных типов документов на странице
2
Временная ошибка

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

1{
2  "status":200,
3  "body":{
4  "objects":[
5     {
6     "status":0,
7     "name":"file_0"
8     },
9     {
10     "status":1,
11     "name":"file_1",
12     "error":"The memory contains data of an unknown image type"
13     }
14     ]
15  },
16  "htmlencoded":false,
17  "last_modified":0
18  }

Recognize

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

Запрос

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

ПараметрТипЗначение
oauth_token
string
OAuth2 access token (required non-empty)
oauth_provider
string
Провайдер OAuth2 (required non-empty)

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

ПровайдерЗначение oauth_providerПолучение токена
VK Cloud
mcs
https://mcs.mail.ru/help/vision-auth/vision-token (все клиенты VK Cloud)

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

ПараметрТипПо умолчаниюЗначение
space
string
--
Числовой идентификатор, используемый для избежания пересечений по персонам (required non-empty)
create_new
bool
false
Добавлять ли новый person, если не было найдено совпадений
images
[]image_meta
--
Метаданные передаваемых изображений (required non-empty)

Описание параметра space смотрите в разделе метода Set.

image_meta

ПараметрТипЗначение
name
string
Имена файлов для сопоставления файлов в запросе и ответе (required non-empty)

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

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

POST /api/v1/objects/detect?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="meta"

{"mode":["object","scene","car_number"],"images":[{"name":"file_0"},{"name":"file_1"}]}
------WebKitFormBoundaryfCqTBHeLZlsicvMp--

Ответ

ПараметрТипЗначение
status
int
200 в случае успешного взаимодействия с серверами Vision
body
response
Тело ответа

response

ПараметрТипЗначение
objects
[]object
Массив ответов для каждого файла
aliases_changed
bool
Изменились ли алиасы

object

ПараметрТипЗначение
status
enum
Результат выполнения
error
string
Текстовое описание ошибки (optional)
name
string
Имя файла для сопоставления файлов в запросе и ответе
labels
[]label
Список объектов (меток), найденных на изображении
count_by_density
int
Количество людей в кадре, подсчитанное с помощью карты плотности (только для mode=”pedestrian”)

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.

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

1{
2  "status":200,
3  "body":{
4     "objects":[
5        {
6           "status":0,
7           "name":"file_0"
8        },
9        {
10           "status":1,
11           "name":"file_1",
12           "error":"The memory contains data of an unknown image type"
13        },
14        {
15           "status":0,
16           "name":"file_2",
17           "persons":[
18              {
19                 "tag":"person9",
20                 "coord":[149,60,234,181],
21                 "confidence":0.9999,
22                 "similarity":0.9987,
23                 "awesomeness":0.45,
24                           "sex":"female",
25                           "emotion":"Sadness",
26                           "age":30.0,
27                           "valence":-0.6184,
28                         "arousal":-0.0578
29              },
30              {
31                 "tag":"person10",
32                 "coord":[159,70,224,171],
33                 "confidence":0.9998,
34                 "similarity":0.9987,
35                 "awesomeness":0.32,
36               "sex":"male",
37               "emotion":"Sadness",
38               "age":22.0,
39               "valence":-0.8184,
40               "arousal":-0.0578
41              }
42           ]
43        },
44        {
45           "status":0,
46           "name":"file_3",
47           "persons":[
48              {
49                 "tag":"person11",
50                 "coord":[157,60,232,111],
51                 "aliases":["person12", "person13"],
52                 "confidence":0.9998,
53                 "similarity":0.9987,
54                 "awesomeness":0.32,
55               "sex":"female",
56               "emotion":"Sadness",
57               "age":12.0,
58               "valence":-0.8184,
59               "arousal":-0.0578
60              }
61           ]
62        },
63        {
64           "status":0,
65           "name":"file_4",
66           "persons":[
67              {
68                 "tag":"undefined",
69                 "coord":[147,50,222,121],
70                 "confidence":0.9997,
71                 "similarity":0.9987,
72                 "awesomeness":0.26,
73               "sex":"male",
74               "emotion":"Sadness",
75               "age":27.0,
76               "valence":0.3184,
77               "arousal":0.1518
78              }
79           ]
80        }
81     ],
82     "aliases_changed":false
83  },
84  "htmlencoded":false,
85  "last_modified":0
86}

Delete

Данный метод позволяет удалить связь между фотографией и person_id.

Запрос

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

ПараметрТипЗначение
oauth_token
string
OAuth2 access token (required non-empty)
oauth_provider
string
Провайдер OAuth2 (required non-empty)

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

ПровайдерЗначение oauth_providerПолучение токена
Mail.Ru
mcs
Смотрите в статье

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

ПараметрТипЗначение
space
string
числовой идентификатор, используемый для избежания пересечений по персонам (required non-empty)
images
[]image_meta
метаданные передаваемых изображений (required non-empty)

Описание параметра space смотрите в разделе метода Set.

image_meta

ПараметрТипЗначение
name
string
Имена файлов для сопоставления файлов в запросе и ответе (required non-empty)
person_id
int
ID, сопоставляемый персоне на фото (required non-empty)

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

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

POST /api/v1/persons/delete?oauth_provider=mr&oauth_token=123 HTTP/1.1
ConContent-Type: multipart/form-data; boundary=----WebKitFormBoundaryfCqTBHeLZlsicvMp
 
------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="meta"
 
{"space":"0", "images":[{"name":"file_0", "person_id":1},{"name":"file_1", "person_id":2}]}
------WebKitFormBoundaryfCqTBHeLZlsicvMp--

Пример с curl:

1curl "https://smarty.mail.ru/api/v1/persons/delete?oauth_provider=mr&oauth_token=123" \
2    -F meta='{"images":[{"name":"f1", "person_id":1},{"name":"f2", "person_id":2}], "space":"1"}'

Ответ

ПараметрТипЗначение
status
int
200 в случае успешного взаимодействия с серверами Vision
body
response
Тело ответа

response

ПараметрТипЗначение
objects
[]object
Массив ответов для каждого файла

object

ПараметрТипЗначение
status
enum
Результат выполнения
error
string
Текстовое описание ошибки (optional)
name
string
Имя файла для сопоставления файлов в запросе и ответе

status

ПараметрЗначение
0
Успешно
1
Перманентная ошибка
2
Временная ошибка

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

1{
2  "status":200,
3  "body":{
4  "objects":[
5     {
6    "status":0,
7    "name":"file_0"
8     },
9     {
10     "status":1,
11     "name":"file_1",
12     "error":"The memory contains data of an unknown image type"
13     }
14  ]
15  },
16  "htmlencoded":false,
17  "last_modified":0
18  }

Truncate

Данный метод позволяет полностью очистить space.

Запрос

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

ПараметрТипЗначение
oauth_token
string
OAuth2 access token (required non-empty)
oauth_provider
string
Провайдер OAuth2 (required non-empty)

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

ПровайдерЗначение oauth_providerПолучение токена
Mail.Ru
mcs
Смотрите в статье

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

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

Описание параметра space смотрите в разделе метода Set.

Данный запрос не требует передачи изображений.

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

POST /api/v1/persons/truncate?oauth_provider=mcs&oauth_token=123 HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryfCqTBHeLZlsicvMp

------WebKitFormBoundaryfCqTBHeLZlsicvMp
Content-Disposition: form-data; name="meta"

{"space":"1"}
------WebKitFormBoundaryfCqTBHeLZlsicvMp--

Ответ

ПараметрТипЗначение
status
int
200 в случае успешного взаимодействия с серверами Vision
body
response
Тело ответа

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

1{
2"status":200,
3"body":{},
4"htmlencoded":false,
5"last_modified":0
6}

Пример php:

php examples/php/smarty.php "https://smarty.mail.ru/api/v1/persons/truncate?oauth_provider=mcs&oauth_token=e50b000614a371ce99c01a80a4558d8ed93b313737363830" "" '{"space":"1"}'