Обзор

Данный сервис позволяет анализировать фото ЖД вагонов и распознавать восьмизначные номера. Сервис принимает на вход изображение и выдает информацию о каждом обнаруженном номере (положение и сам номер).

Сервис реализован как HTTP API.

Входное изображение можно передать двумя альтернативными способами:

• Как бинарный файл.
• Как url на публичный источник.

Поддерживаются форматы JPEG и PNG. Максимальный размер изображения: 16Mb.

Эндпоинты

Получение версии сервиса

Эндпоинт возвращает версию в формате vX.Y.Z.

Примеры на curl

Запрос:

$ curl -X 'GET' 'https://api4ai.cloud/rzd-train-carriage/v1/version'

Ответ:

v1.0.0

Обработка изображения и получение результатов

Схема ответа

В случае успеха сервис возвращает ответ с HTTP кодом 200 и JSON объект со следующей структурой:

{
  "results": [
    {
      "status": {
        "code": ...,
        "message": ...
      },
      "name": ...,
      "md5": ...,
      "entities": [
        {
          "kind": "objects",
          "name": "train-info",
          "objects": [
            {
              "box": ...,
              "entities": [
                {
                  "kind": "text",
                  "name": "carriage-number",
                  "text": ...
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Основные поля:

Некоторые замечания:

• Координаты объекта определяют прямоугольную область на изображении в формате [x, y, width, height]. При этом все значения нормализованы (т.е. 0.0 – левый или верхний край, 1.0 – правый или нижний край)
• Объектов (номеров вагонов) может быть несколько.
• Все поля, которые не описаны в таблице "основные поля" имеют фиксированные значения, описанные в схеме выше.

Передача изображения

Входное изображение можно передать двумя альтернативными способами:

• Как бинарный файл через поле формы (имя поля – image).
• Как url на публичный источник через поле формы (имя поля – url).

Поддерживаются форматы JPEG и PNG. Максимальный размер изображения: 16Mb.

Примеры на curl

Запрос:

curl -X 'POST' 'https://api4ai.cloud/rzd-train-carriage/v1/results?api_key=...' -F 'image=@image.jpg'

Ответ:

{
  "results": [
    {
      "status": {
        "code": "ok",
        "message": "Success"
      },
      "name": "50649342_51714780.jpg",
      "md5": "6aa1aef726f5af8413314098d1618a05",
      "entities": [
        {
          "kind": "objects",
          "name": "train-info",
          "objects": [
            {
              "box": [
                -0.0046875,
                0.440625,
                0.090625,
                0.020833333333333315
              ],
              "entities": [
                {
                  "kind": "text",
                  "name": "carriage-number",
                  "text": "50649342"
                }
              ]
            },
            {
              "box": [
                0.7171875,
                0.43125,
                0.0734375,
                0.020833333333333332
              ],
              "entities": [
                {
                  "kind": "text",
                  "name": "carriage-number",
                  "text": "51714780"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Авторизация

Некоторые эндпоинты (в частости .../results) требуют авторизации по API ключу.

Сервис поддерживает 3 альтернативных способа передачи API ключа.

Передача API ключа через параметр запросы api_key:

curl 'https://api4ai.cloud/some/end/point?api_key=1234567890'

Передача API ключа через параметр запросы key:

curl 'https://api4ai.cloud/some/end/point?key=1234567890'

Передача API ключа через HTTP заголовок (т.е. HTTP header) x-api-key:

curl -H "x-api-key: 1234567890" 'https://api4ai.cloud/some/end/point'

Замечания к примерам выше:

• API ключ 1234567890 не является примером настоящим ключем. Обратитесь к разработчикам API для получения настоящего ключа.
• Эндпоинт /some/end/point не является примером настоящего эндпоинта. Список натоящих эндпоинтов досупен в разделе "Эндпоинты".

Возможные ошибки

Сервис не может обработать переданное клиентом изображение

Когд переданное изображение не может быть обработано, сервис возвращает ответ со статусом 200. Возвращаемый JSON объект имеет тот же формате, что и в случае успеха. Только в этом случае поле results[].status.code будет иметь значение failure, а поле results[].status.message – описание ошибки.

Некоторые из причин ошибок:

• Неподдерживаемый формат изображения.
• Поврежденное изображение.

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

{
  "results": [
    {
      "status": {
        "code": "failure",
        "message": "Can not load image."
      },
      "name": "file.txt",
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "entities": []
    }
  ]
}

Клиент отправил слишком большой запрос

Ограничение на размер запроса составляет примерно 32Mb. Когда клиент пытается передать слишком большой запрос, то сервис возвращает ответ с кодом 413.

Чтобы укладываться в этот лимит мы настоятельно рекомендуем не передавать изображения размером более, чем 16Mb.

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

Error: Request Entity Too Large

Your client issued a request that was too large.

Клиент не передал изображение

Если клиент не передаёт изображение, то сервер возвращает ответ с кодом 422.

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

{
  "detail": "Missing image or url field."
}

Клиент передал неверный API ключ

Если клиент передаёт API ключ, но он не верный, то сервер возвращает ответ с кодом 400.

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

{
  "message": "INVALID_ARGUMENT:API key not valid. Please pass a valid API key.",
  "code": 400
}

Клиент не передал API ключ

Если клиент передаёт API ключ, то сервер возвращает ответ с кодом 401.

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

{
  "message": "UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
  "code": 401
}