Беттерді тану

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` мәні	Токенді алу
VK Cloud	mcs	мақаладан қараңыз

Сұрау параметрлері сұрау денесінде name="meta" арқылы JSON форматында беріледі:

Параметр	Тип	Мәні
space	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атаулары (required non-empty)
images	[]image_meta	Фотодағы персонаға сәйкестендірілетін ID (required non-empty)

space параметрі person бойынша қиылысуларды болдырмау үшін пайдаланылады. Осылайша, space 0 ішіндегі person1 және space 1 ішіндегі person1 әртүрлі. Әртүрлі міндеттерді орындайтын қолданбалар үшін space параметрінің әртүрлі мәндерін пайдалану орынды.

Клиентте 10 түрлі space дейін болуы мүмкін. space мәндері 0-ден 9-ға дейін өзгереді. Лимит асып кеткен жағдайда қате қайтарылады.

image_meta параметрлері:

Параметр	Тип	Мәні
name	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атаулары (required non-empty)
person_id	int	Фотодағы персонаға сәйкестендірілетін ID (required non-empty)

Кескіндер сұрау денесінде беріледі, name өрісінің мәндері images ішінде берілгендерге сәйкес келуі тиіс.

Сұрау мысалы


curl -X 'POST' "https://smarty.mail.ru/api/v1/persons/set?oauth_token=<ВАШ_ТОКЕН>&oauth_provider=mcs"      \  -H 'accept: application/json' \  -H 'Content-Type: multipart/form-data' \  -F 'file=@persons_set_ok.jpg;type=image/jpeg' \  -F 'meta={  "space": "5",  "images": [    {      "name": "file",      "person_id": 1    }  ]}'

Жауап

Параметр	Тип	Мәні
status	int	Vision серверлерімен сәтті өзара әрекеттесу болған жағдайда 200
body	response	Жауап денесі

response параметрлері:

Параметр	Тип	Мәні
objects	[]object	әрбір файл үшін жауаптар массиві

object параметрлері:

Параметр	Тип	Мәні
status	enum	Орындау нәтижесі: - `0` — сәтті; - `1` — беттегі табылған құжат түрлерінің массиві; - `2` — уақытша қате
error	string	Қатенің мәтіндік сипаттамасы (optional)
name	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атауы

Жауап мысалы


{  "status": 200,  "body": {    "objects": [      {        "status": 0,        "name": "file"      }    ]  },  "htmlencoded": false,  "last_modified": 0}

Қосымша мысалдар

Өрістерді валидациялау қатесі (файл атауларының формаға сәйкес келмеуі)

Кескінде адамның беті жоқ

Бірнеше беті бар кескін

Бос кескін

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	мақаладан қараңыз

Сұрау параметрлері сұрау денесінде name="meta" арқылы JSON форматында беріледі:

Параметр	Тип	Әдепкі бойынша	Мәні
space	string	--	Персоналар бойынша қиылыстарды болдырмау үшін пайдаланылатын сандық идентификатор (required non-empty)
create_new	bool	false	Егер сәйкестіктер табылмаса, жаңа person қосу керек пе
images	[]image_meta	--	Берілетін кескіндердің метадеректері (required non-empty)
update_embedding	bool	true	Жаңа персона үшін embedding жаңарту керек пе
searcher	int	0	Тану үшін модельді таңдау: `0` — барлық персоналар бойынша іздеу (бірінші модель), `1` — ең жақын көршіні іздеу (екінші модель)

Белгілі персона танылған сайын, болашақта осы персонаны жақсырақ тану үшін беттің векторлық көрінісі (embedding) жаңартылады. Алайда кейбір жағдайларда update_embedding параметрі арқылы автожаңартуды өшірген дұрыс, мысалы фотосуреттердің сапасы нашар екені алдын ала белгілі болса.

space параметрінің сипаттамасын Set әдісі бөлімінен қараңыз.

image_meta параметрлері:

Параметр	Тип	Мәні
name	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атаулары (required non-empty)

Кескіндер сұрау денесінде беріледі, name өрісінің мәндері images ішінде берілгендерге сәйкес келуі тиіс.

Сұрау мысалы


curl -X 'POST' \  'https://smarty.mail.ru/api/v1/persons/recognize?oauth_token=<ВАШ_ТОКЕН>&oauth_provider=mcs' \  -H 'accept: application/json' \  -H 'Content-Type: multipart/form-data' \  -F 'file=@persons_recognize_ok_person_in_db.jpg;type=image/jpeg' \  -F 'meta={  "space": "5",  "create_new": false,  "images": [    {      "name": "file"    }  ]}'

Жауап

Параметр	Тип	Мәні
status	int	Vision серверлерімен сәтті өзара әрекеттесу болған жағдайда `200`
body	response	Жауап денесі

response параметрлері:

Параметр	Тип	Мәні
objects	[]object	Әрбір файл үшін жауаптар массиві
aliases_changed	bool	Алиастар өзгерді ме

object параметрлері:

Параметр	Тип	Мәні
status	enum	Орындау нәтижесі: - `0` — сәтті; - `1` — тұрақты қате; - `2` — уақытша қате
error	string	Қатенің мәтіндік сипаттамасы (optional)
name	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атауы
persons	[]person	Фотосуреттен табылған персоналар тізімі

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-ге дейін)

Тек екінші модель үшін (сұрауда searcher = 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 - белсенді адам]

Сұраудағы create_new мәні false болғанда және ұсынылған кескін бойынша дерекқорда сәйкес person табылмаса, tag мәні undefined болуы мүмкін.

Жауап мысалы


{  "status": 200,  "body": {    "objects": [      {        "status": 0,        "name": "file",        "persons": [          {            "tag": "person1",            "coord": [              567,              376,              992,              931            ],            "confidence": 0.99917,            "awesomeness": 0.4894,            "similarity": 0.9721,            "sex": "male",            "emotion": "Neutral",            "age": 34,            "valence": -0.3236,            "arousal": 0.185,            "frontality": 0.8921,            "visibility": 0.9985          }        ]      }    ]  },  "htmlencoded": false,  "last_modified": 0}

Қосымша мысалдар

Кескіндегі бет дерекқорда жоқ және create_new=true

Кескінде бет жоқ

Кескіндегі бет дерекқорда жоқ және create_new=false

JSON құрастыру қатесі

Жарамсыз кескін

Delete

Бұл әдіс фотосурет пен person_id арасындағы байланысты жоюға мүмкіндік береді.

Сұрау

Авторизация деректері сұрау жолында беріледі:

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

Қолдау көрсетілетін OAuth2 провайдерлері:

Провайдер	`oauth_provider` мәні	Токенді алу
VK Cloud	mcs	мақаладан қараңыз

Сұрау параметрлері сұрау денесінде name="meta" арқылы JSON форматында беріледі:

Параметр	Тип	Мәні
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 ішінде берілгендерге сәйкес келуі тиіс.

Сұрау мысалы


curl -X 'POST' \  'https://smarty.mail.ru/api/v1/persons/delete?oauth_token=<ВАШ_ТОКЕН>&oauth_provider=mcs' \  -H 'accept: application/json' \  -H 'Content-Type: multipart/form-data' \  -F 'meta={  "space": "5",  "images": [    {      "name": "aaa",      "person_id": 1    }  ]}'

Жауап

Параметр	Тип	Мәні
status	int	Vision серверлерімен сәтті өзара әрекеттесу болған жағдайда `200`
body	response	Жауап денесі

response параметрлері:

Параметр	Тип	Мәні
objects	[]object	Әрбір файл үшін жауаптар массиві

object параметрлері:

Параметр	Тип	Мәні
status	enum	Орындау нәтижесі: - `0` — сәтті; - `1` — тұрақты қате; - `2` — уақытша қате
error	string	Қатенің мәтіндік сипаттамасы (optional)
name	string	Сұрау мен жауаптағы файлдарды сәйкестендіруге арналған файл атауы

Жауап мысалы


{  "status": 200,  "body": {    "objects": [      {        "status": 0,        "name": "aaa"      }    ]  },  "htmlencoded": false,  "last_modified": 0}

Қосымша мысалдар

JSON валидациясы қатесі (person_id жоқ)

Truncate

Бұл әдіс space-ті толық тазалауға мүмкіндік береді.

Сұрау

Авторизация деректері сұрау жолында беріледі:

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

Қолдау көрсетілетін OAuth2 провайдерлері:

Провайдер	`oauth_provider` мәні	Токенді алу
VK Cloud	mcs	мақаладан қараңыз

Сұрау параметрлері сұрау денесінде name="meta" арқылы JSON форматында беріледі:

Параметр	Тип	Мәні
space	string	Персоналар бойынша қиылыстарды болдырмау үшін пайдаланылатын сандық идентификатор (required non-empty)

space параметрінің сипаттамасын Set әдісі бөлімінен қараңыз.

Бұл сұрау кескіндерді жіберуді қажет етпейді.

Сұрау мысалы


curl -X 'POST' \  'https://smarty.mail.ru/api/v1/persons/truncate?oauth_token=<ВАШ_ТОКЕН>&oauth_provider=mcs' \  -H 'accept: application/json' \  -H 'Content-Type: multipart/form-data' \  -F 'meta={  "space": "5"}'

Жауап

Параметр	Тип	Мәні
status	int	Vision серверлерімен сәтті өзара әрекеттесу болған жағдайда `200`
body	response	Жауап денесі

Жауап мысалы


{  "status": 200,  "body": {},  "htmlencoded": false,  "last_modified": 0}

Қосымша мысалдар

JSON валидациясы қатесі (`space` өрісі жоқ)

Мақала пайдалы болды ма?

Мазмұны
Set
Recognize
Delete
Truncate
Мақала пайдалы болды ма?