VK Cloud logo
Обновлена31 октября 2023 г. в 06:09

Распознавание полей документов

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

HOST: https://smarty.mail.ru

ENDPOINT: /api/v1/docs/recognize

Запрос

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

Параметр
Тип
Значение
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":

Параметр
Тип
Значение
images
[]image_meta
Метаданные передаваемых изображений (required non-empty)

Параметры image_meta:

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

Изображения передаются в теле запроса, значения поля name должны соответствовать переданным в images.

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/docs/recognize?oauth_token=<ваш токен>&oauth_provider=mcs' \
3  -H 'accept: application/json' \
4  -H 'Content-Type: multipart/form-data' \
5  -F 'file=@docs_recognize_ok.jpg;type=image/jpeg' \
6  -F 'meta={
7  "images": [
8    {
9      "name": "file"
10    }
11  ]
12}'

Ответ

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

Параметры response:

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

Параметры object:

Параметр
Тип
Значение
status
enum
Результат выполнения:
- 0 — успешно;
- 1 — перманентная ошибка;
- 2 — временная ошибка
error
string
Текстовое описание ошибки (опционально)
name
string
Имя файла для сопоставления файлов в запросе и ответе
labels
object
Распознанные поля документа

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

1{
2  "status": 200,
3  "body": {
4    "objects": [
5      {
6        "status": 0,
7        "name": "file",
8        "labels": {
9          "birthday": [
10            "10.04.1990"
11          ],
12          "birthplace": [
13            "ГОР.",
14            "МОСКВА"
15          ],
16          "code_of_issue": [
17            "459-653"
18          ],
19          "date_of_issue": [
20            "11.11.1995"
21          ],
22          "first_name": [
23            "ФОМА"
24          ],
25          "last_name": [
26            "КИНЯЕВ"
27          ],
28          "middle_name": [
29            "СЕМЕНОВИЧ"
30          ],
31          "number": [
32            "233675"
33          ],
34          "place_of_issue": [
35            "ГОРОДА",
36            "МОСКВЫ",
37            "ОДИНЦОВСКОГО",
38            "РАЙОНА",
39            "ОТДЕЛОМ",
40            "ВНУТРЕННИХ",
41            "ДЕЛ"
42          ],
43          "series_number": [
44            "560Р"
45          ],
46          "sex": [
47            "МУЖ."
48          ]
49        }
50      }
51    ]
52  },
53  "htmlencoded": false,
54  "last_modified": 0
55}

Дополнительные примеры

Поля на изображении не распознаны

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/docs/recognize?oauth_token=<ваш токен>&oauth_provider=mcs' \
3  -H 'accept: application/json' \
4  -H 'Content-Type: multipart/form-data' \
5  -F 'file=@docs_recognize_not_doc.jpg;type=image/jpeg' \
6  -F 'meta={
7  "images": [
8    {
9      "name": "file"
10    }
11  ]
12}'

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

1{
2  "status": 200,
3  "body": {
4    "objects": [
5      {
6        "status": 0,
7        "name": "file",
8        "labels": {}
9      }
10    ]
11  },
12  "htmlencoded": false,
13  "last_modified": 0
14}

Невалидное изображение

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/docs/recognize?oauth_token=<ваш токен>&oauth_provider=mcs' \
3  -H 'accept: application/json' \
4  -H 'Content-Type: multipart/form-data' \
5  -F 'file=@empty.jpg;type=image/jpeg' \
6  -F 'meta={
7  "images": [
8    {
9      "name": "file"
10    }
11  ]
12}'

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

1{
2  "status": 400,
3  "body": "could not get image by name file1: http: no such file",
4  "htmlencoded": false,
5  "last_modified": 0
6}

Некорректный JSON (несовпадение имени в meta и изображении)

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/docs/recognize?oauth_token=<ваш токен>&oauth_provider=mcs' \
3  -H 'accept: application/json' \
4  -H 'Content-Type: multipart/form-data' \
5  -F 'file=@persons_set_ok.jpg;type=image/jpeg' \
6  -F 'meta={
7  "images": [
8    {
9      "name": "file1"
10    }
11  ]
12}'

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

1{
2  "status": 400,
3  "body": "could not get image by name file1: http: no such file",
4  "htmlencoded": false,
5  "last_modified": 0
6}