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

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

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

HOST: https://smarty.mail.ru

ENDPOINT: /api/v1/docs/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":

Параметр
Тип
Значение
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/detect?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 в случае успешного взаимодействия с серверами Vision
body
string
Тело ответа

Параметры response:

Параметр
Тип
Значение
status
enum
Результат выполнения:
- 0 — успешно;
- 1 — перманентная ошибка;
- 2 — временная ошибка
error
string
Текстовое описание ошибки (optional)
name
string
Имя файла для сопоставления файлов в запросе и ответе
pages
[]page
Список объектов (меток), найденных на изображении

Параметры page:

Параметр
Тип
Значение
index
int
Номер страницы
docs
[]doc
Массив найденных типов документов на странице

Параметры doc:

Параметр
Значение
eng
Тип (название) документа на английском
rus
Тип (название) документа на русском
prob
Степень уверенности в том, что на изображении именно этот тип документа

Для каждого объекта (картинки) может быть несколько типов, с различной степенью уверенности. Метка «Документ» определяет является ли изображение документом и с какой вероятностью. На данный момент поддерживаются следующие типы документов:

Eng метка
Rus метка
Akt
Акт
Akt_sverky
Акт сверки
Diplom
Диплом
Doc
Документ
Dogovor
Договор
Doverennost
Доверенность
Inn
ИНН
Logotip
Логотип
Pasport
Паспорт
Prais_list
Прайс-лист
Prikaz
Приказ
Protocol
Протокол
Pts
ПТС
Registraciya_ts
Регистрация ТС
Rekvizity
Реквизиты
Rezyume
Резюме
Schet
Счет
Sertifikat
Сертификат
Snils
Снилс
Spravka
Справка
Svidetelstvo
Свидетельство
Tabel
Табель
Ustav
Устав
Voditelskye_prava
Водительские права
Vypiska
Выписка
Zagranpasport
Загранпаспорт
Zayavlenie
Заявление

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

1{
2  "status": 200,
3  "body": {
4    "status": 0,
5    "objects": [
6      {
7        "status": 0,
8        "name": "file",
9        "pages": [
10          {
11            "index": 0,
12            "docs": [
13              {
14                "eng": "Pasport",
15                "rus": "Паспорт",
16                "probability": 0.475
17              }
18            ]
19          }
20        ]
21      }
22    ]
23  },
24  "htmlencoded": false,
25  "last_modified": 0
26}

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

Распознавание водительского удостоверения

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

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

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

1{
2  "status": 200,
3  "body": {
4    "status": 0,
5    "objects": [
6      {
7        "status": 0,
8        "name": "file",
9        "pages": [
10          {
11            "index": 0,
12            "docs": [
13              {
14                "eng": "Voditelskye_prava",
15                "rus": "Водительские права",
16                "probability": 0.8387
17              }
18            ]
19          }
20        ]
21      }
22    ]
23  },
24  "htmlencoded": false,
25  "last_modified": 0
26}

На изображении нет документа

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

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

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

1{
2  "status": 200,
3  "body": {
4    "status": 0,
5    "objects": [
6      {
7        "status": 0,
8        "name": "file",
9        "pages": [
10          {
11            "index": 0,
12            "docs": []
13          }
14        ]
15      }
16    ]
17  },
18  "htmlencoded": false,
19  "last_modified": 0
20}

Ошибка в формировании JSON (несовпадение имени в meta и изображении)

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/docs/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \
3  -H 'accept: application/json' \
4  -H 'Content-Type: multipart/form-data' \
5  -F 'file=@docs_detect_ok_prava.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}