Загрузите фотографию
JPEG / PNG / WebP, до 12 МБ
Браузерный тест ограничен 30 запросами в час с одного IP. Для интеграции используйте API с токеном.
Результат
REST API — интеграция для внешних систем
Сервис определяет по фотографии наличие бланка «Курьер Сервис Экспресс» (в том числе частично видимого, повёрнутого или оборотной стороны) и наличие подписей/печати. Ответ — структурированный JSON.
Базовый URL: https://pics.tikhov.de/api. Аутентификация: заголовок
Authorization: Bearer <токен> (или X-Api-Key).
Токен выпускается на вкладке «API-токены».
Ограничения и форматы
| Форматы изображений | JPEG, PNG, WebP, GIF. Формат определяется по содержимому файла, расширение может быть любым |
|---|---|
| Максимальный размер файла | 12 МБ (для всех трёх способов передачи). Превышение — ошибка 413 too_large |
| Разрешение | Ограничений нет: изображения крупнее 1600px по длинной стороне сервис сжимает автоматически. Рекомендуемый минимум для надёжного распознавания — ~800px по длинной стороне |
Модели (параметр model) | claude-sonnet-4-6 — по умолчаниюclaude-haiku-4-5-20251001claude-sonnet-5claude-opus-4-6 |
| Лимит запросов | 60 запросов в минуту на токен по умолчанию; настраивается при выпуске токена (rate_limit_per_min) |
| Время обработки | Обычно 4–15 секунд на фото (зависит от модели). Устанавливайте таймаут HTTP-клиента не менее 120 секунд |
| Требования к image_url | Только http/https, публично доступный адрес (не внутренняя сеть), скачивание — до 20 секунд, размер — в пределах лимита файла |
GET /v1/health — проверка доступности сервиса. Без аутентификации.
POST /v1/analyze — анализ фотографии.
Три способа передать изображение:
1. multipart/form-data, поле image (+ необязательное поле model):
curl -X POST https://pics.tikhov.de/api/v1/analyze \ -H "Authorization: Bearer kse_ВАШ_ТОКЕН" \ -F "image=@photo.jpg"
2. JSON + base64:
curl -X POST https://pics.tikhov.de/api/v1/analyze \
-H "Authorization: Bearer kse_ВАШ_ТОКЕН" \
-H "Content-Type: application/json" \
-d '{"image_base64": "<base64-строка>", "model": "claude-sonnet-4-6"}'
3. JSON + URL: {"image_url": "https://…/photo.jpg"}
Ответ 200
{
"status": "ok",
"processing_ms": 8412,
"result": {
"is_kse_form": true, // на фото есть бланк КСЭ (целиком или частично)
"confidence": 0.98, // уверенность 0..1
"form_visibility": "full", // full | partial | none
"form_side": "front", // front | back | both | unknown
"matched_features": ["логотип КСЭ", "www.cse.ru", "номер 497-…", "разделы 1-11"],
"waybill_number": "497-020135258",
"has_signature": true, // есть хоть одна рукописная подпись
"signatures": {
"recipient": true, // подпись получателя (разд. 11 / оборот)
"sender_or_courier": false, // подпись отправителя/курьера
"stamp": true // печать организации
},
"signature_confidence": 0.93,
"image_quality": "ok", // ok | blurry | dark | partial_glare | unreadable
"reason": "Виден полный бланк КСЭ: логотип, номер, разделы…",
"model": "claude-sonnet-4-6",
"usage": { // расход токенов AI-модели (для контроля затрат)
"input_tokens": 1599,
"output_tokens": 214,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 2210 // >0 — системный промпт взят из кеша (дешевле)
}
}
}
Поле waybill_number — вспомогательное: на фронтальных фото и сканах читается точно,
на снимках под сильным углом возможны ошибки в отдельных цифрах. Используйте его для сверки с вашей системой,
а не как первичный ключ. Основные поля для решений — is_kse_form и has_signature с их confidence.
Ошибки
Формат: {"error": {"code": "...", "message": "текст на русском"}}
| HTTP | code | Когда возникает |
|---|---|---|
| 400 | no_image | В запросе нет изображения (нет поля image / image_base64 / image_url) |
| 400 | bad_input | Файл не является изображением, неподдерживаемый формат или недопустимая модель |
| 400 | bad_base64 | image_base64 — некорректный base64 |
| 400 | bad_url / fetch_failed | image_url: не http/https, внутренний адрес, или скачать не удалось |
| 400 | bad_upload | Ошибка multipart-загрузки (файл оборван и т.п.) |
| 401 | unauthorized | Токен отсутствует, не найден или отозван |
| 403 | forbidden | Неверный X-Admin-Key (для админ-эндпоинтов) |
| 413 | too_large | Файл больше 12 МБ (запросы существенно больше лимита сервер отклоняет на уровне nginx без JSON-тела) |
| 429 | rate_limited | Превышен лимит запросов в минуту для токена — повторите через 60 секунд |
| 502/503 | upstream_error | Временный сбой AI-провайдера — повторите с экспоненциальной задержкой (сервис сам делает 3 попытки до ответа) |
POST /v1/tokens · GET /v1/tokens · DELETE /v1/tokens/{id} — управление токенами. Требуют заголовок X-Admin-Key.
Выпуск: JSON-тело {"label": "название интеграции", "rate_limit_per_min": 120}
(rate_limit_per_min необязателен, по умолчанию 60).
Ответ 201 содержит поле token — показывается только один раз, в БД хранится лишь SHA-256 хеш.
DELETE отзывает токен (мягко: токен перестаёт работать, история запросов сохраняется).
GET /v1/stats — статистика использования (X-Admin-Key):
количество запросов за сегодня и всего, доли «бланк найден»/«подпись найдена», среднее время обработки.
Рекомендации для продакшна
Оптимальный размер фото — до 1600px по длинной стороне (крупнее сервис сожмёт сам).
Модель по умолчанию claude-sonnet-4-6 — точность 24/24 на эталонном наборе; claude-haiku-4-5 — быстрее и дешевле (23/24).
При массовой обработке шлите запросы параллельно (лимит токена по умолчанию 60/мин, настраивается при выпуске).
Решение принимайте по паре полей: is_kse_form && confidence ≥ 0.8, подпись — has_signature && signature_confidence ≥ 0.7; пограничные случаи отправляйте на ручную проверку.