Написать в техподдержку Позвонить нам
Админпанель Выход

Содержание статьи:

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

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

    • Set
    • Recognize
    • Delete
    • 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 метаданные передаваемых изображений (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 метаданные передаваемых изображений (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 в случае успеха, иначе описание ошибки будет в body

    body string | response 

    тело ответа

    response

    Параметр Тип Значение
    objects

    []object

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

    object

    Параметр Тип Значение
    status

    enum

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


    error

    string

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

    name

    string

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

    status

    Параметр Значение
    0

    успешно

    1

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

    2

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

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

    {

    "status":200,

    "body":{

    "objects":[

       {

       "status":0,

       "name":"file_0"

       },

       {

       "status":1,

       "name":"file_1",

       "error":"The memory contains data of an unknown image type"

       }

       ]

    },

    "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

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

    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
    }

    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 используется для избежания пересечений по 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/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:

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

    Ответ

    Параметр Тип Значение
    status  int  200 в случае успеха, иначе описание ошибки будет в body
    body  string  тело ответа

    response

    Параметр Тип Значение
    objects  []object

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

    object

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

    status

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

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

    {

    "status":200,

    "body":{

    "objects":[

       {

      "status":0,

      "name":"file_0"

       },

       {

       "status":1,

       "name":"file_1",

       "error":"The memory contains data of an unknown image type"

       }

    ]

    },

    "htmlencoded":false,

    "last_modified":0

    }

    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 в случае успеха, иначе описание ошибки будет в body
    body string | response  тело ответа

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

    {

    "status":200,

    "body":{},

    "htmlencoded":false,

    "last_modified":0

    }

    Пример php:

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


    Полезна ли была эта статья?