Общие методы

В этом разделе:

Метод /detect POST

Данный метод служит для обнаружения лица на изображении. Вы можете задать изображение в виде файла с составным содержимым (multipart/form-data) или предоставить ссылку на изображение в сети Интернет.

Параметры:

  • photo: загруженная фотография или публичный URL фотографии.
  • gender: если true, возвращает информацию о поле
  • age: если true, возвращает информацию о возрасте
  • emotions: если true, возвращает инфомацию об эмоциях

Возвращает:

  • Список координат рамок вокруг обнаруженных лиц.

Пример

Запрос

POST /v1/detect/ HTTP/1.1
Host: 192.168.113.76:8000
Connection:close
Authorization: Token BpdNA6eaUlN9bPhXVSK1r92_SFOODPOU
Content-Type:   application/json
Content-Length: 108

{
    "photo": "https://static.findface.pro/sample.jpg",
    "emotions": true,
    "gender": true,
    "age": true
}

Ответ

HTTP/1.1 200 OK
Date: Thu, 06 Apr 2017 12:38:40 GMT
Server: TornadoServer/4.4.2
Content-Length: 120
Content-Type: application/json; charset=UTF-8


{
  "faces": [
    {
     "age": 26,
     "emotions": [
       "neutral",
       "sad"
     ],
     "gender": "female",
     "x1": 595,
     "x2": 812,
     "y1": 127,
     "y2": 344
    }
  ]
}

Метод /verify POST

Данный метод сравнивает две фотографии, проверяя, принадлежит ли изображенное на них лицо одному и тому же человеку, и возвращает степень схожести двух лиц. Дополнительно степень схожести может сравниваться с заданным пороговым значением для принятия однозначного решения о совпадении лиц.

В случае если требуется однозначное решение о совпадении лиц, на Сервер необходимо передать ненулевое значение параметра threshold. Вы можете использовать одно из 3-х предустановленных значений: strict, medium или low. Вы также можете задать собственное пороговое значение.

В случае если нужно просто вычислить степень схожести 2-х лиц, а не верифицировать идентичность, передайте параметр threshold со значением none.

Примечание

Если параметр threshold не передан, его значение по умолчанию устанавливается равным 0.75.

Совет

При необходимости свяжитесь с нашими специалистами для подбора оптимального порогового значения для вашей системы.

Параметры:

  • photo1: первая загруженная фотография или публичный URL фотографии.

  • photo2: вторая загруженная фотография или публичный URL фотографии.

  • bbox1 [опционально]: массив рамок с лицами на первом фото, которые нужно сравнить.

  • bbox2 [опционально]: массив рамок с лицами на втором фото, которые нужно сравнить.

  • threshold [опционально]: пороговая степень схожести лиц для принятия положительного решения о совпадении. Задайте значение от 0 до 1 или используйте предустановленный порог: «strict» (высокий), «medium» (средний), «low» (низкий, установлен по умолчанию), «none» (не задан). По умолчанию сравнение выполняется при 0.75.

  • mf_selector [опционально]: задает поведение Сервера при наличии нескольких лиц на фотографии. Возможные значения mf_selector:

    • "reject": возвращает ошибку, если хотя бы на одной из фотографий присутствует более одного лица.
    • "biggest" [по умолчанию]: проверяет самое большое лицо на фотографии.
    • "all": проверяет схожесть всех лиц, обнаруженных на обеих фотографиях.

    Примечание

    Параметры bbox1 и bbox2 отменяют значение этого параметра.

Возвращает:

  • Результат верификации: совпадает или не совпадает. Результат возвращается, если задано пороговое значение верификации. При наличии нескольких лиц на фотографиях результат указывается как для каждой пары лиц, так и на уровне фотографий. На уровне фотографий результат верификации будет положительным, если каждая пара лиц на них совпадает.
  • Координаты рамок с лицами на фотографиях.
  • Вероятность совпадения (степень схожести) лиц от 0 до 1.

Пример

Запрос

POST /v0/verify/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json
Content-Length: [length]

{
  "photo1": "http://static.findface.pro/sample.jpg",
  "photo2": "http://static.findface.pro/sample2.jpg"
}

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": [
    {
      "bbox1": {
        "x1": 225,
        "x2": 307,
        "y1": 345,
        "y2": 428
      },
      "bbox2": {
        "x1": 78,
        "x2": 185,
        "y1": 114,
        "y2": 222
      },
      "confidence": 0.4206026792526245,
      "verified": true
    }
  ],
  "verified": true
}

Метод /identify POST

Данный метод используется для поиска лица в базе биометрических данных и возвращает выборку лиц, если степень их схожести с искомым выше определенного порогового значения.

Параметры:

  • photo: загруженная фотография или публичный URL фотографии.

  • x1, y1, x2, y2 [опционально]: координаты прямоугольника на фотографии, внутри которого находится искомое лицо(а).

  • threshold [опционально]: пороговая степень схожести лиц для принятия положительного решения о совпадении. Задайте значение от 0 до 1 или используйте предустановленный порог: «strict» (высокий), «medium» (средний), «low» (низкий, установлен по умолчанию), «none» (не задан). По умолчанию сравнение выполняется при 0.75.

  • n [опционально]: максимальное число лиц в выборке, одно по умолчанию.

  • strict [опционально]: задает поведение Сервера на случай, если один или несколько шардов tntapi недоступны. Данный параметр имеет приоритет над параметром tntapi_ignore_search_errors в файле конфигурации findface-facenapi.

    • True: возвращает ошибку, если некоторые шарды tntapi недоступны.
    • False [по умолчанию]: Сервер использует доступные шарды tntapi для получения результатов идентификации лица и указывает в ответе отношение количества доступных шардов tntapi к их общему количеству в заголовке X-Live-Servers.

  • mf_selector [optional]: задает поведение Сервера при наличии нескольких лиц на фотографии или внутри заданного прямоугольника. Возможные значения:

    • "reject": возвращает ошибку, если хотя бы на одной из фотографий присутствует более одного лица.
    • "biggest" [по умолчанию]: поиск по базе данных выполняется для самого крупного лица на фотографии.
    • "all": поиск по базе данных выполняется по всем лицам на фотографии.

Возвращает:

  • Координаты рамок с лицами, найденными на фотографии. Для каждого набора координат возвращается массив схожих лиц из базы биометрических данных вместе с вероятностью совпадения от 0 до 1.

Пример

Запрос

POST /v0/identify/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json
Content-Length: [length]

{
  "n": 10,
  "photo": "http://static.findface.pro/sample.jpg"
}

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": {
    "[419, 236, 345, 311]": [
      {
        "confidence": 1,
        "face": {
          "galleries": ["default", "ppl"]
          "id": 316275,
          "meta": "Sam Berry",
          "photo": "http://static.findface.pro/sample.jpg",
          "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
          "timestamp": "2016-07-01T12:18:27.477653",
          "x1": 236,
          "x2": 311,
          "y1": 345,
          "y2": 419
        }
      },
      {
        "confidence": 0.723975,
        "face": {
          "galleries": ["default", "ppl"]
          "id": 316283,
          "meta": "Sam Berry",
          "photo": "http://test.flexify.io/img/sample2.jpg",
          "photo_hash": "9b1dd93259fe87df122cd678ce95b9f9",
          "timestamp": "2016-07-01T13:19:36.376548",
          "x1": 78,
          "x2": 185,
          "y1": 114,
          "y2": 222
        }
      }
    ]
  }
}

Метод /face POST

Данный метод обрабатывает загруженное изображение или изображение в сети Интернет, обнаруживает на нем лица и добавляет их вместе с векторами признаков в базу биометрических данных. Если на изображении несколько лиц, то по умолчанию в базу данных добавляется только самое крупное. Вместе с лицом вы также можете добавить метаданные, которые являются уникальными для его обладателя, например, идентификатор или имя. Не рекомендуется назначать одинаковые метаданные разным людям. При необходимости вы можете указать имя галереи, в которую нужно добавить лицо помимо галереи по умолчанию.

Параметры:

  • photo: загруженная фотография или публичный URL фотографии.

  • meta [опционально]: пользовательские метаданные.

  • bbox [опционально]: массив рамок, содержащих лица на изображении.

  • mf_selector [опционально]: задает поведение Сервера при наличии нескольких лиц на фотографии или внутри заданного прямоугольника. Возможные значения:

    • "reject": возвращает ошибку, если хотя бы на одной из фотографий присутствует более одного лица.
    • "biggest" [по умолчанию]: проверяет самое большое лицо на фотографии.
    • "all": добавляет все лица, обнаруженные на фотографии. Имейте в виду, что в этом случае метаданные будут одинаковыми для всех лиц.

  • galleries [опционально]: список имен галерей, в которые необходимо добавить лицо.

  • cam_id [опционально]: UUID видеокамеры, от которой пришло изображение лица.

Возвращает:

  • Представление данных добавленного лица в JSON или ошибку при добавлении.
  • В случае если на изображении было обнаружено несколько лиц и значение mf_selector="reject", метод возвращает код ошибки 400 (Bad Request), а также список координат рамок для каждого обнаруженного лица.

Пример №1

Запрос

POST /v0/face/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json
Content-Length: [length]

{
  "meta": "Sam Berry",
  "photo": "http://static.findface.pro/sample.jpg",
  "galleries": ["gal1", "niceppl"]
}

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 06:04:02 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: [length]

{
  "results": [
    {
      "galleries": ["default", "gal1", "niceppl"]
      "id": 2334,
      "meta": "Sam Berry",
      "photo": "http://static.findface.pro/sample.jpg",
      "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
      "timestamp": "2016-06-13T11:11:29.425339",
      "x1": 225,
      "x2": 307,
      "y1": 345,
      "y2": 428
    }
  ]
}

Пример №2

Запрос

POST /v0/face/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json
Content-Length: [length]

{
  "mf_selector": "reject",
  "photo": "http://static.findface.pro/sample-multiface.jpg"
}

Ответ

HTTP/1.1 400 Bad Request
Date: Mon, 13 Jun 2016 06:04:02 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: [length]

{
  "code": 400,
  "faces": [
    {
      "x1": 1952,
      "x2": 2137,
      "y1": 838,
      "y2": 1023
    },
    {
      "x1": 1766,
      "x2": 1952,
      "y1": 1312,
      "y2": 1498
    },
    {
      "x1": 1385,
      "x2": 1540,
      "y1": 939,
      "y2": 1094
    },
    {
      "x1": 2452,
      "x2": 2607,
      "y1": 664,
      "y2": 818
    },
    {
      "x1": 1609,
      "x2": 1764,
      "y1": 767,
      "y2": 922
    }
  ],
  "reason": "Too many faces: 5"
}

Метод /face/id/<id> GET

Данный метод возвращает подробную информацию о лице с заданным id.

Параметры:

  • Отсутствуют.

Возвращает:

  • Представление данных лица с определенным id в JSON.

Пример

Запрос

GET /v0/face/id/2333/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "galleries": ["default", "ppl"]
  "id": 2333,
  "meta": "Sam Berry",
  "photo": "http://static.findface.pro/sample.jpg",
  "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
  "timestamp": "2016-06-13T11:06:42.075754",
  "x1": 225,
  "x2": 307,
  "y1": 345,
  "y2": 428
}

Метод /face/id/<id> PUT

Данный метод используется для изменения значений полей объекта лицо с заданным id.

Параметры:

  • meta: новые метаданные.
  • person_id: уникальный идентификатор персоны в базе данных.
  • galleries: словарь JSON с одной парой ключ-значение. Вы можете добавить, удалить или полностью изменить список пользовательских галерей, в которых хранится лицо: {"add":["list","of","galleries"]}, {"del":["list","of","galleries"]}, {"set":["list","of","galleries"]}.

Возвращает:

  • Представление обновленных данных лица в JSON.

Пример

Запрос

PUT /v0/face/id/5/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json
Content-Length: [length]

{
  "meta": "Sam Berry #2"
}

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "id": 2333,
  "meta": "Sam Berry #2",
  "photo": "http://static.findface.pro/sample2.jpg",
  "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
  "timestamp": "2016-06-13T11:06:42.075754",
  "x1": 225,
  "x2": 307,
  "y1": 345,
  "y2": 428
}

Метод /face/id/<id> DELETE

Данный метод удаляет лицо с заданным id.

Параметры:

  • Отсутствуют.

Возвращает:

  • HTTP 204 No Content в случае успеха или причину ошибки.

Пример

Запрос

DELETE /v0/face/id/2332/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token ca7916cdac260628c411cb5d895dd566
Content-Length: 0

Ответ

HTTP/1.1 204 No Content

Метод /face/meta/<meta> GET

Возвращает список лиц с заданными метаданными. Имейте в виду, что данный метод чувствителен к регистру. Строка с метаданными должна быть в кодировке URL. Пробелы между словами в метаданных должны быть закодированы как %20.

Параметры:

  • Отсутствуют.

Возвращает:

  • Возвращает список лиц с заданными метаданными.

Пример

Запрос

GET /v0/face/meta/Sam%20Berry/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": [
    {
      "galleries": ["default", "ppl"],
      "id": 2333,
      "meta": "Sam Berry",
      "photo": "http://static.findface.pro/sample.jpg",
      "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
      "timestamp": "2016-06-13T11:06:42.075754",
      "x1": 225,
      "x2": 307,
      "y1": 345,
      "y2": 428
    },
    {
      "galleries": ["default", "ppl"],
      "id": 2378,
      "meta": "Sam Berry",
      "photo": "http://static.findface.pro/sample2.jpg",
      "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
      "timestamp": "2016-06-13T11:06:42.075754",
      "x1": 46,
      "x2": 502,
      "y1": 472,
      "y2": 789
    }
  ]
}

Метод /faces GET

Параметры:

  • Отсутствуют.

Возвращает:

  • Данный метод возвращает список всех лиц в базе биометрических данных.

Пример

Запрос

GET /v0/faces/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": [
    {
      "galleries": ["default", "ppl"]
      "id": 2333,
      "meta": "Sam Berry",
      "photo": "http://static.findface.pro/sample.jpg",
      "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
      "timestamp": "2016-06-13T11:06:42.075754",
      "x1": 225,
      "x2": 307,
      "y1": 345,
      "y2": 428
    },
    {
      "galleries": ["default", "ppl"]
      "id": 2335,
      "meta": "",
      "photo": "http://static.findface.pro/sample2.jpg",
      "photo_hash": "9879efb38d2dae550460c9edb6f36982",
      "timestamp": "2016-06-13T11:34:57.275394",
      "x1": 8,
      "x2": 152,
      "y1": 406,
      "y2": 550
    }
  ]
}

Метод /meta GET

Данный метод возвращает все уникальные строки с метаданными, хранящимися в базе данных. Для каждой строки возвращается одно из связанных с ней лиц. Для того чтобы получить все лица, связанные с той или иной строкой, используйте метод GET /v0/face/meta/<meta>.

Параметры:

  • Отсутствуют.

Возвращает:

  • Список объектов, содержащих уникальные строки с метаданными, количество лиц, связанных с той или иной строкой, JSON-представление данных первого лица, связанного со строкой.

Пример

Запрос

GET /v0/meta/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": [
    {
      "count": 1,
      "face": {
        "galleries": ["default", "ppl"]
        "id": 2333,
        "meta": "Sam Berry",
        "photo": "http://static.findface.pro/sample.jpg",
        "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
        "timestamp": "2016-06-13T11:06:42.075754",
        "x1": 225,
        "x2": 307,
        "y1": 345,
        "y2": 428
      },
      "meta": "Sam Berry"
    },
    {
      "galleries": ["default", "ppl"]
      "count": 15,
      "face": {
        "id": 2563,
        "meta": "Angelina Jolie",
        "photo": "http://static.findface.pro/sample2.jpg",
        "photo_hash": "dc7ac54590729669ca869a18d92cd05e",
        "timestamp": "2016-06-13T11:06:42.075754",
        "x1": 225,
        "x2": 307,
        "y1": 345,
        "y2": 428
      },
      "meta": "Angelina Jolie"
    }
  ]
}

Метод /galleries GET

Данный метод возвращает список всех существующих галерей в базе данных.

Возвращает:

  • Словарь JSON со списком имен (id) галерей.

Пример

Запрос

GET /v0/galleries/ HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e

Ответ

HTTP/1.1 200 OK
Date: Mon, 13 Jun 2016 12:23:56 GMT
Content-Type: application/json
Content-Length: [length]

{
  "results": [
    "default",
    "test"
    "57bd75f941741d36ab4614a0",
    "57bd76a241741d377bf881ac",
  ]
}

Метод /galleries/<gallery> POST

Данный метод создает новую галерею с заданным именем. Имя галереи может содержать латинские буквы, числа, знак подчеркивания и минус ([a-zA-Z0-9_-]+) и не может быть длиннее 48 символов.

Параметры:

Отсутствуют.

Пример

Запрос

POST /v0/galleries/testgal HTTP/1.1
Host: 127.0.0.1
Authorization: Token e93437ccdae66d57a45a5c6d9aa7602e
Content-Type: application/json

Ответ

HTTP/1.1 201 Created
Date: Mon, 13 Jun 2016 06:04:02 GMT

Метод /docs GET

Данный метод возвращает список всех задокументированных версий API. Доступен без авторизации.

Метод /docs/<version> GET

Данный метод возвращает документацию к заданной версии API. Доступен без авторизации.

Метод /person/id/<id> GET

Параметры:

  • Отсутствуют.

Возвращает:

  • Представление данных человека с заданным person_id в JSON.

Пример

Запрос

GET    /person/history/id/2001 HTTP/1.1
Host:   127.0.0.1
Authorization:  Token   e93437ccdae66d57a45a5c6d9aa7602e
Content-Type:   application/json
Content-Length: [length]
{
    "cam_ids":    [1, 25, 26, 27],
    "start":  "2016-06-13T11:00:00.000000",
    "end":    "2016-06-14T11:00:00.000000"
}

Ответ

HTTP/1.1   200 OK
Date:   Mon,    13  Jun 2016    12:23:56    GMT
Content-Type:   application/json
Content-Length: [length]
{
    "results":
    [
        {
            "person_id":  2001,
            "face_id":    240344,
            "cam_id": 25,
            "meta":   "Sam   Berry",
    "screenshot":"https://static.findface.pro/57726179d6946f02f3763824/dc7ac54590729669ca869a18d92cd05e_thumb.j
pg",
            "timestamp":  "2016-06-13T11:06:42.075754",
        },
        {
            "person_id":  2001,
            "face_id":    240422,
            "cam_id": 25,
            "meta":   "Sam   Berry",
            "screenshot": "https://static.findface.pro/57726179
d6946f02f3763824/dc7ac54590729669ca869a18d92cd05e_thumb.j
pg",
            "timestamp":  "2016-06-13T11:08:44.073452",
        }
    ]
}

Метод /history/search POST

Данный метод возвращает все события по видеокамере(ам), удовлетворяющие заданным условиям.

Параметры:

  • "person_id" [опционально]: значение параметра person_id интересующего человека.
  • "cam_id" [опционально]: массив id видеокамер.
  • "start" [опционально]: время начала событий в формате ISO8601.
  • "end" [опционально]: время конца событий в формате ISO8601.
  • "friend" [опционально]: является ли человек «своим».
  • "limit" [опционально]: количество записей на странице, по умолчанию 0 — не ограничено.

Возвращает:

  • Список всех событий истории.
  • next_page: URL к следующей странице результатов поиска (содержит путь и указатель на следующую порцию результатов). Если такого поля нет в ответе, значит, была выведена последняя страница.

Пример

Запрос

POST /v0/history/search    HTTP/1.1
Host:   127.0.0.1
Authorization:  Token   e93437ccdae66d57a45a5c6d9aa7602e
Content-Type:   application/json
Content-Length: [length]
{
    "limit": 2,
}

Ответ

HTTP/1.1   200 OK
Date:   Mon,    12  Oct 2016    12:23:56    GMT
Content-Type:   application/json
Content-Length: [length]
{
   "next_page": "/v0/history/search?max_id=4",
   "results":[
      {
         "friend":false,
         "meta":"",
         "photo_hash":"9fda49f2444f93c33ad8aa914e20e53b",
         "cam_id":"12345678123456781234567812345678",
         "person_id":8,
         "timestamp":"2016-10-11T14:36:27.450000",
         "photo":"",
         "id":20146,
         "y1":77,
         "x1":285,
         "x2":552,
         "y2":345
      },
      {
         "friend":false,
         "meta":"",
         "photo_hash":"dc7ac54590729669ca869a18d92cd05e",
         "cam_id":"12345678123456781234567812345678",
         "person_id":8,
         "timesamp":"2016-10-12T12:57:07.509000",
         "photo":"",
         "id":20147,
         "x1":236,
         "y1":345,
         "x2":311,
         "y2":419
      }
   ]
}