API-K Агрегатор - доступ к API реесторв и сервисов

Введение

API для распознавания сканированных документов (OCR API) — это мощный инструмент для извлечения текстовой информации из изображений, PDF-файлов и сканированных документов. Эндпоинт /api/recognize предоставляет возможность преобразования визуального контента в машинно-читаемый формат с использованием передовых алгоритмов компьютерного зрения и машинного обучения.

Назначение

Эндпоинт предназначен для автоматизации процессов обработки документов, включая: - Распознавание текста с изображений и PDF-документов - Обработку паспортов, водительских удостоверений и других типов документов - Поддержку многоязычного контента - Извлечение структурированных данных с информацией о расположении текста

Детализация параметров запроса

Тело запроса (application/json)

content (обязательный)

Тип: string
Формат: Base64 encoded image
Описание: Содержимое файла, закодированное в формате Base64. Поддерживаются изображения и PDF-файлы.

Пример:

{
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
}

model (обязательный)

Тип: string
Допустимые значения: - "passport" — для распознавания паспортов и удостоверений личности - "page" — для обычных текстовых страниц - "license_car" — для автомобильных прав и свидетельств

Рекомендации по выбору: - Используйте passport для документов с фиксированной структурой - Выбирайте page для книг, статей и произвольных текстов - Применяйте license_car для транспортных документов

languageCodes (опциональный)

Тип: array[string]
По умолчанию: ["ru", "en"]
Описание: Список языков для распознавания. Поддерживается приоритетность: первый язык в списке имеет высший приоритет.

Примеры:

["ru"] // Только русский язык
["en", "ru"] // Английский с fallback на русский

mimeType (обязательный)

Тип: string
Допустимые значения: - "image/jpeg" — для JPEG изображений - "application/pdf" — для PDF-документов

Ограничения: - Максимальный размер файла: 2MB - Для PDF: максимум 1 страница за запрос

Примеры использования

Пример 1: Распознавание паспорта

cURL запрос:

curl -X POST "https://api-k.ru/api/recognize" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "content": "base64_encoded_image_data",
    "model": "passport",
    "languageCodes": ["ru"],
    "mimeType": "image/jpeg"
  }'

Python пример:

import requests
import base64

def recognize_document(image_path, api_key):
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    
    url = "https://api-k.ru/api/recognize"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": api_key
    }
    
    data = {
        "content": encoded_string,
        "model": "passport",
        "languageCodes": ["ru"],
        "mimeType": "image/jpeg"
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Использование
result = recognize_document("passport.jpg", "ваш_api_ключ")

Пример 2: Обработка многоязычного документа

data = {
    "content": base64_encoded_pdf,
    "model": "page",
    "languageCodes": ["en", "ru", "de"],
    "mimeType": "application/pdf"
}

Обработка ответов

Успешный ответ (HTTP 200)

Структура ответа:

{
  "result": {
    "textAnnotation": {
      "fullText": "Полный распознанный текст...",
      "pages": [
        {
          "property": {
            "detectedLanguages": [
              {"languageCode": "ru", "confidence": 0.95}
            ]
          },
          "width": 800,
          "height": 600,
          "blocks": [
            {
              "boundingBox": {
                "vertices": [
                  {"x": 10, "y": 10},
                  {"x": 790, "y": 10},
                  {"x": 790, "y": 590},
                  {"x": 10, "y": 590}
                ]
              },
              "lines": [
                {
                  "boundingBox": {...},
                  "words": [
                    {
                      "boundingBox": {...},
                      "text": "Пример",
                      "confidence": 0.99
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Коды ошибок (HTTP 4xx/5xx)

Код	Ошибка	Описание
400	`Invalid base64 content`	Неверный формат Base64
400	`Unsupported mime type`	Неподдерживаемый тип файла
400	`File size exceeded`	Превышен максимальный размер файла
401	`Invalid API key`	Неверный или отсутствующий API-ключ
500	`Internal server error`	Внутренняя ошибка сервера

Пример ошибки:

{
  "error": "Invalid base64 content",
  "details": "The provided content is not valid base64 encoded data"
}

Best Practices

1. Подготовка изображений

Используйте разрешение не менее 300 DPI
Обеспечьте хорошее освещение и контрастность
Избегайте искажений и наклонов

2. Оптимизация запросов

# Правильно: сжатие изображения перед отправкой
from PIL import Image
import io

def optimize_image(image_path, max_size=1024):
    img = Image.open(image_path)
    img.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
    
    buffer = io.BytesIO()
    img.save(buffer, format='JPEG', quality=85, optimize=True)
    return base64.b64encode(buffer.getvalue()).decode('utf-8')

3. Обработка больших документов

def process_large_pdf(pdf_path, api_key):
    # Разбиваем PDF на страницы и обрабатываем по одной
    for page_num in range(total_pages):
        page_image = extract_page_as_image(pdf_path, page_num)
        encoded_content = base64.b64encode(page_image).decode('utf-8')
        
        data = {
            "content": encoded_content,
            "model": "page",
            "mimeType": "image/jpeg"
        }
        
        # Добавляем задержку между запросами
        time.sleep(0.5)
        response = make_api_request(data, api_key)

4. Валидация данных

def validate_request_data(data):
    required_fields = ['content', 'model', 'mimeType']
    for field in required_fields:
        if field not in data:
            raise ValueError(f"Missing required field: {field}")
    
    if data['mimeType'] not in ['image/jpeg', 'application/pdf']:
        raise ValueError("Unsupported mime type")
    
    if len(data['content']) > 10 * 1024 * 1024:  # 10MB
        raise ValueError("File size too large")

Ограничения и лимиты

Технические ограничения

Максимальный размер файла: 2 MB
Максимальное количество страниц PDF: 1
Максимальное разрешение изображения: 4096x4096 px
Поддерживаемые форматы: JPEG, PDF

Бизнес-лимиты

Rate limiting: 60 запросов в минуту
Ежедневный лимит: 10,000 запросов
Требуется аутентификация: Обязательное использование API-ключа

Заключение

Наш API сервис предоставляет надежное решение для задач оптического распознавания символов. Правильное использование параметров модели, валидация входных данных и соблюдение best practices обеспечат максимальную точность распознавания и стабильность работы системы.

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

Техническая документация: REST API эндпоинт /api/recognize