VK Cloud logo
Обновлена18 августа 2023 г. в 12:48

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

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

HOST: https://smarty.mail.ru

ENDPOINT: /api/v1/text/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)
mode
string
Параметр-флаг: выдавать ли детализированный ответ, если "detailed", то детализированный (к ответу добавляются координаты bounding box текста и confidence), (optional)

Параметры image_meta:

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

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

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/text/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}'

Ответ

ПараметрТипЗначение
status
int
200 в случае успешного взаимодействия с серверами Vision
body
response
Тело ответа

Параметры response:

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

Параметры object:

ПараметрТипЗначение
status
enum
Результат выполнения:
- 0 — успешно;
- 1 — перманентная ошибка;
- 2 — временная ошибка
error
string
Текстовое описание ошибки (optional)
name
string
Имя файла для сопоставления файлов в запросе и ответе
text
string
Распознанный текст
results
[]line
Если проставлен "mode":"detailed" — массив строк ответов по странице (текст, bounding box, confidence)

Параметры line:

ПараметрТипЗначение
line_prob
float32
Уверенность распознавания строки
line_coord
[]float32
Координаты строки - x1,y1, x2, y2 - левый верхний и правый нижний точки охватывающего прямоугольника
words
[]word
Массив распознанных слов ответов в строке

Параметры word:

ПараметрТипЗначение
prob
float32
Уверенность распознавания слова
coord
[]float32
Координаты слова - x1,y1, x2, y2 - левый верхний и правый нижний точки охватывающего прямоугольника
text
string
Массив распознанных слов ответов в строке
lang_prob
float32
Уверенность распознавания языка
lang
string
Eng/rus/unknown. Unknown когда не содержит букв алфавита

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

1{
2  "status": 200,
3  "body": {
4    "objects": [
5      {
6        "status": 0,
7        "name": "file",
8        "text": "Когда пришла весна,\nнаступили теплые дни. Там,\nгде раньше лежал снег,\nвесело бегут ручьи. Куда\nни взглянешь, всюду\nрасцветают подснежники.\nЕсли посмотреть на\nвесеннее небо, то можно\nувидеть стаи птиц,\nлетящих с юга. Когда\nпросыпается природа от\nзимнего сна, лес\nнаполняется весенней"
9      }
10    ]
11  },
12  "htmlencoded": false,
13  "last_modified": 0
14}

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

mode=detailed

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/text/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  "mode": "detailed",
8  "images": [
9    {
10      "name": "file"
11    }
12  ]
13}'

На изображении нет текста

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/text/recognize?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  "mode": "detailed",
8  "images": [
9    {
10      "name": "file"
11    }
12  ]
13}'

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

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

Пустое изображение

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/text/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  "mode": "detailed",
8  "images": [
9    {
10      "name": "file"
11    }
12  ]
13}'

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

1{
2  "status": 400,
3  "body": "empty image",
4  "htmlencoded": false,
5  "last_modified": 0
6}

Некорректный JSON

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

1curl -X 'POST' \
2  'https://smarty.mail.ru/api/v1/text/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  "mode": "detailed",
8  "images": [
9    {
10      "name": "file1"
11    }
12  ]
13}'

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

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}