Обновлена 31 октября 2023 г. в 06:09
Распознавание объектов
Данный метод позволяет найти различные объекты на фотографии.
HOST: https://smarty.mail.ru
ENDPOINT: /api/v1/objects/detect
Авторизационные данные передаются в строке запроса:
Параметр | Тип | Значение |
|---|---|---|
oauth_token | string | OAuth2 access token (required non-empty) |
oauth_provider | string | Провайдер OAuth2 (required non-empty) |
Поддерживаемые провайдеры OAuth2:
Провайдер | Значение oauth_provider | Получение токена |
|---|---|---|
VK Cloud | mcs | Смотрите в статье |
Параметры запроса передаются в формате JSON в теле запроса с name="meta":
Параметр | Тип | Значение |
|---|---|---|
mode | []string | Типы объектов, которые требуется искать на переданных изображениях (required non-empty) |
images | []image_meta | Метаданные передаваемых изображений (required non-empty) |
Возможные значения mode:
Параметр | Тип |
|---|---|
object | Искать на изображении объекты |
object2 | Искать на изображении объекты (версия модели v2 — распознает объекты, принадлежащие большему количеству классов) |
scene | Искать на изображении сцены |
car_number | Искать на изображении номера машин |
multiobject | Искать на изображении мультиобъекты — объекты и все множество боксов всех найденных объектов |
pedestrian | Искать на изображении людей (более точно определяет множество боксов всех людей на изображении) |
mode может содержать один или несколько режимов. Например:
"mode":["object"]<-- искать только объекты;"mode":["scene"]<-- искать только сцены;"mode":["object","scene"]<-- искать сцены и объекты.
Параметры image_meta:
Параметр | Тип | Значение |
|---|---|---|
name | string | Имена файлов для сопоставления файлов в запросе и ответе (required non-empty) |
Изображения передаются в теле запроса, значения поля name должны соответствовать переданным в images.
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@objects_detect_ok_people_in_theatre.jpg;type=image/jpeg' \-F 'meta={"mode": ["scene","multiobject","pedestrian"],"images": [{"name": "file"}]}'
Параметр | Тип | Значение |
|---|---|---|
status | int | 200 в случае успешного взаимодействия с серверами Vision |
body | response | Тело ответа |
Параметры response:
Параметр | Тип | Значение |
|---|---|---|
scene_labels | []object | Массив ответов для каждого файла со сценами (может отсутствовать) |
object_labels | []object | Массив ответов для каждого файла с объектами (может отсутствовать) |
car_number_labels | []object | Массив ответов для каждого файла с номерам машин (может отсутствовать) |
multiobject_labels | []object | Массив ответов для каждого файла с мультиобъектами (может отсутствовать) |
pedestrian_labels | []object | Массив ответов для каждого файла с людьми (может отсутствовать) |
Параметры object:
Параметр | Тип | Значение |
|---|---|---|
status | enum | Результат выполнения: - 0 — успешно;- 1 — перманентная ошибка;- 2 — временная ошибка |
error | string | Текстовое описание ошибки (optional) |
name | string | Имя файла для сопоставления файлов в запросе и ответе |
labels | []label | Список объектов (меток), найденных на изображении |
count_by_density | int | Количество людей в кадре, подсчитанное с помощью карты плотности (только для mode="pedestrian") |
Параметры label:
Параметр | Значение |
|---|---|
eng | Метка (название) для найденного объекта на английском |
rus | Метка (название) найденного объекта на русском |
eng_categories | Список категорий (каждая категория включает в себя множество меток) на английском (optional) |
rus_categories | Список категорий (каждая категория включает в себя множество меток) на русском (optional) |
prob | Степень уверенности в том, что на изображении именно этот объект |
coord | Координаты найденного объекта (optional) |
types_prob | Массив вероятностей типов номерных знаков. на данный момент поддерживаются следующие типы: "rus" — все типы Российских номеров; "cis" — номера СНГ (кроме индивидуальных и военных украинских); "eu" — одноэтажные номера Европы (optional, only for car_number mode) |
Пример запроса:
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@persons_set_error_no_face.jpg;type=image/jpeg' \-F 'meta={"mode": ["object","scene"],"images": [{"name": "file"}]}'
Пример запроса (невалидный JSON):
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@objects_detect_ok_people_in_theatre.jpg;type=image/jpeg' \-F 'meta={"mode": ["sceneaaaa","multiobjet"],"images": [{"name": "file"}]}'
Пример запроса (невалидное изображение):
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@empty.jpg;type=image/jpeg' \-F 'meta={"mode": ["scene","multiobjeсt"],"images": [{"name": "file"}]}'
Пример ответа:
{"status": 400,"body": "empty image","htmlencoded": false,"last_modified": 0}