API

API

На этой странице собраны основные backend-эндпоинты.

Базовый префикс API:

/v1

Авторизация

Для meal-эндпоинтов backend ожидает два заголовка:

Authorization: Bearer <SECRET_KEY>
x-tg-user-id: <telegram_user_id>

Именно так бот идентифицирует пользователя и подтверждает, что запрос пришёл от доверенного клиента.

GET /v1/health

Простой healthcheck-роут.

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

{
  "status": "healty"
}

Да, в ответе сейчас именно строка "healty".
Это не страшно, просто текущая реализация в коде.

GET /v1/meal/last

Возвращает последнюю запись пользователя.

Что делает

• берёт x-tg-user-id из заголовка;
• ищет последнюю запись в БД;
• если запись есть — возвращает её;
• если нет — отдаёт 404.

Возможный ответ

{
  "id": 15,
  "tg_user_id": 123456789,
  "text": "рис с курицей",
  "created_at": "2026-04-23T14:20:00",
  "calories": 540,
  "protein": 35.0,
  "fat": 12.0,
  "carbs": 60.0,
  "llm_raw": {
    "micro": [
      {"name": "B3", "percent_dv": 25},
      {"name": "Selenium", "percent_dv": 19}
    ]
  },
  "confidence": 89
}

DELETE /v1/meal/last

Удаляет последнюю запись пользователя и возвращает её же в ответе.

GET /v1/meal/today

Возвращает сумму КБЖУ за текущий день.

Идея

Backend агрегирует все записи пользователя за текущую дату и возвращает общий итог.

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

{
  "calories": 1200,
  "protein": 75.0,
  "fat": 40.0,
  "carbs": 130.0
}

Замечание

Если за сегодня записей нет, в ответе могут прийти пустые значения.
Поэтому на клиенте это стоит учитывать отдельно.

POST /v1/meal/

Главный эндпоинт проекта.

Сюда отправляется:

• текстовое описание еды;
• опционально — изображение блюда.

Формат запроса

multipart/form-data

Поля формы

• text — обязательное текстовое описание
• file — необязательный файл изображения

Пример: только текст

curl -X POST "http://localhost:8000/v1/meal/" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "x-tg-user-id: 123456789" \
  -F "text=гречка с куриной грудкой"

Пример: текст + изображение

curl -X POST "http://localhost:8000/v1/meal/" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "x-tg-user-id: 123456789" \
  -F "text=Проанализируй это изображение" \
  -F "[email protected]"

Что делает backend внутри

После запроса backend:

1. проверяет, что текст не пустой;
2. находит или создаёт пользователя;
3. отправляет текст и/или картинку в LLM;
4. получает JSON с оценкой еды;
5. проверяет, что запрос вообще про еду;
6. проверяет confidence;
7. сохраняет запись в БД;
8. возвращает готовую запись.

Основные ошибки

400 Bad Request

Возвращается, если:

• запрос пустой;
• модель считает, что это не еда;
• запрос слишком странный или плохо формулирован;
• входные данные не удалось корректно обработать.

401 Unauthorized

Возвращается, если неверный SECRET_KEY.

404 Not Found

Актуально, например, для GET /meal/last и DELETE /meal/last, если записей у пользователя нет.

429 Too Many Requests

Возвращается, если внешний LLM-сервис временно недоступен или ограничивает запросы.

Для чего нужен x-tg-user-id

Проект хранит данные не “вообще”, а отдельно по Telegram-пользователю.

То есть два разных человека, даже если отправят один и тот же текст, будут иметь разные записи в БД.
Это и даёт изоляцию пользовательских данных.