API эндпоинты

Интерактивная документация: /redoc (ReDoc), /docs (Swagger UI), /openapi.json.

Аутентификация

Сервис использует схему VK Mini Apps. Клиент отправляет параметры запуска VK и подпись (sign). Сервер верифицирует подпись с помощью VK_SECRET_KEY и выдаёт JWT.

Authorization: Bearer <jwt_token>

POST /api/v1/photo/auth

Аутентификация VK. Проверка подписи HMAC-SHA256. Возвращает JWT.

Request:
{
  "vk_user_id": "123456789",
  "vk_app_id": "987654",
  "sign": "base64url_hmac_signature",
  "vk_language": "ru",
  "vk_platform": "desktop_web"
}

Response 200:
{
  "auth_token": "eyJhbGciOiJIUzI1NiIs..."
}

POST /api/v1/photos/

Загрузить фото (multipart/form-data, JPEG/PNG, ≤3MB).

Response 202:
{
  "photo_id": "p_a1b2c3d4e5f6",
  "status": "pending",
  "message": "Фото приняты в асинхронную обработку"
}

GET /api/v1/photos/

Список фото (публичные — если без токена, свои — если с токеном).

GET /api/v1/photos/{id}

Детали фото с результатами анализа (faces_count, blur_score, quality_metric, и т.д.).

GET /api/v1/photos/{id}/content

Presigned URL для доступа к оригиналу и превью.

GET /api/v1/duplicate-groups/

Список групп дубликатов.

GET /api/v1/duplicate-groups/{id}

Детали группы с лучшим фото (по quality_metric).

GET /healthz

{"status": "ok"}

GET /readyz

Проверяет PostgreSQL и MinIO.

{"status": "ok", "checks": {"database": "ok", "storage": "ok"}}

Статусы фото

uploading  — файл загружается
pending    — ожидает обработки
processing — обрабатывается worker-ом
done       — анализ завершён
failed     — анализ не удался

Формат ошибок

{
  "error": {
    "code": "PHOTO_NOT_FOUND",
    "message": "Photo 'p_abc123' not found"
  },
  "request_id": "a1b2c3d4e5f6"
}

Коды: VALIDATION_ERROR (400), ACCESS_DENIED (403), PHOTO_NOT_FOUND (404), FILE_TOO_LARGE (413), INVALID_FILE_TYPE (415), DATABASE_ERROR (503).