StickerAI-Front/API_DOCUMENTATION.md

# API Документация

## Обзор

API предоставляет функциональность для работы со стикерами в Telegram, включая генерацию изображений, создание стикерпаков и управление ими. Также API поддерживает отслеживание позиций задач в очереди.

Базовый URL: `http://localhost:8001`

## Эндпоинты

### Проверка работоспособности

#### GET /health

Проверяет работоспособность API.

**Ответ:**
```json
{
  "status": "ok"
}
```

### Управление пользователями

#### POST /register

Регистрирует нового пользователя в системе.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "username": "example_user",
  "chat_id": 123456789,
  "balance": 0
}
```

**Параметры:**
- `user_id` (integer, обязательный): Уникальный ID пользователя (например, из Telegram)
- `username` (string, обязательный): Имя пользователя
- `chat_id` (integer, обязательный): ID чата
- `balance` (integer, опциональный, по умолчанию 0): Начальный баланс пользователя

**Ответ (201 Created):**
```json
{
  "user_id": 123456789,
  "username": "example_user",
  "chat_id": 123456789,
  "balance": 0
}
```

**Ошибки:**
- 400 Bad Request: Пользователь с таким chat_id уже существует

#### GET /users/{user_id}

Получает информацию о пользователе по его ID.

**Параметры пути:**
- `user_id` (integer, обязательный): ID пользователя

**Ответ (200 OK):**
```json
{
  "user_id": 123456789,
  "username": "example_user",
  "chat_id": 123456789,
  "balance": 0
}
```

**Ошибки:**
- 404 Not Found: Пользователь не найден

### Генерация изображений и управление очередью

#### POST /generate_image

Создает задачу на генерацию изображения с использованием ComfyUI.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "workflow": {
    // Объект workflow для ComfyUI
  },
  "tag": "image_generation"
}
```

**Параметры:**
- `user_id` (integer, обязательный): ID пользователя
- `workflow` (object, обязательный): Объект workflow для ComfyUI
- `tag` (string, обязательный): Тег для типа задачи (допустимое значение: "image_generation")

**Ответ (200 OK):**
```json
{
  "message": "Ваше изображение генерируется, пожалуйста подождите, готовое изображение будет у вас в галереи",
  "Task_ID": "123",
  "queue_position": 5
}
```

**Ошибки:**
- 400 Bad Request: Недопустимый тег
- 404 Not Found: Пользователь не найден
- 500 Internal Server Error: Ошибка при создании задачи или отправке сообщения

#### GET /user_pending_tasks/{user_id}

Получает список задач пользователя в статусе PENDING с их позициями в очереди.

**Параметры пути:**
- `user_id` (integer, обязательный): ID пользователя

**Ответ (200 OK):**
```json
[
  {
    "task_id": 123,
    "prompt_id": "prompt_id_from_comfyui",
    "status": "PENDING",
    "created_at": "2025-03-13T11:15:00",
    "queue_position": 3,
    "updated_at": "2025-03-13T11:20:00"
  },
  {
    "task_id": 124,
    "prompt_id": "prompt_id_from_comfyui_2",
    "status": "STARTED",
    "created_at": "2025-03-13T11:10:00",
    "queue_position": null,
    "updated_at": "2025-03-13T11:20:00"
  }
]
```

**Ошибки:**
- 404 Not Found: Пользователь не найден
- 500 Internal Server Error: Внутренняя ошибка сервера

#### GET /task_position/{task_id}

Получает текущую позицию задачи в очереди.

**Параметры пути:**
- `task_id` (integer, обязательный): ID задачи

**Ответ (200 OK):**
```json
{
  "task_id": 123,
  "status": "PENDING",
  "queue_position": 3
}
```

**Ошибки:**
- 404 Not Found: Задача не найдена
- 500 Internal Server Error: Внутренняя ошибка сервера

#### GET /images_links/{user_id}

Получает список ссылок на изображения пользователя.

**Параметры пути:**
- `user_id` (integer, обязательный): ID пользователя

**Ответ (200 OK):**
```json
[
  {
    "id": 1,
    "link": "file_id_from_telegram",
    "prompt_id": "prompt_id_from_comfyui",
    "status": "COMPLETED",
    "created_at": "2025-03-12T12:00:00",
    "sticker_set_id": null
  }
]
```

**Ошибки:**
- 404 Not Found: Пользователь не найден

### Управление стикерами

#### POST /upload_sticker

Загружает файл стикера на сервер Telegram.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "link": "https://example.com/image.png"
}
```

**Параметры:**
- `user_id` (integer, обязательный): ID пользователя
- `link` (string, обязательный): URL или путь к файлу стикера

**Ответ (200 OK):**
```json
{
  "file_id": "file_id_from_telegram"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при загрузке файла на сервер Telegram

#### POST /create_sticker_set

Создает новый набор стикеров.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "sticker_set_name": "example_set",
  "title": "Example Sticker Set",
  "file_id": "file_id_from_telegram",
  "emojis": "😀",
  "is_animated": false,
  "is_video": false
}
```

**Параметры:**
- `user_id` (integer, обязательный): ID пользователя
- `sticker_set_name` (string, обязательный): Название набора стикеров (без суффикса _by_bot)
- `title` (string, обязательный): Заголовок набора стикеров
- `file_id` (string, обязательный): File_id загруженного стикера
- `emojis` (string, обязательный): Список эмодзи для стикера
- `is_animated` (boolean, опциональный, по умолчанию false): Флаг анимированного стикера
- `is_video` (boolean, опциональный, по умолчанию false): Флаг видео-стикера

**Ответ (200 OK):**
```json
{
  "message": "Новый набор стикеров успешно создан!",
  "name": "example_set_by_bot_name"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при создании набора стикеров

#### POST /add_sticker_to_set

Добавляет стикер в существующий набор.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "sticker_set_name": "example_set",
  "file_id": "file_id_from_telegram",
  "emojis": "😀",
  "is_animated": false,
  "is_video": false
}
```

**Параметры:**
- `user_id` (integer, обязательный): ID пользователя
- `sticker_set_name` (string, обязательный): Название набора стикеров (без суффикса _by_bot)
- `file_id` (string, обязательный): File_id загруженного стикера
- `emojis` (string, обязательный): Список эмодзи для стикера
- `is_animated` (boolean, опциональный, по умолчанию false): Флаг анимированного стикера
- `is_video` (boolean, опциональный, по умолчанию false): Флаг видео-стикера

**Ответ (200 OK):**
```json
{
  "message": "Стикер успешно добавлен в набор!"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при добавлении стикера в набор

#### GET /check_sticker_set_name/{sticker_set_name}

Проверяет, существует ли набор стикеров с указанным именем.

**Параметры пути:**
- `sticker_set_name` (string, обязательный): Название набора стикеров

**Ответ (200 OK):**
```json
{
  "exists": true
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при проверке существования набора стикеров

#### POST /delete_sticker_from_set

Удаляет стикер из набора.

**Тело запроса:**
```json
{
  "file_id": "file_id_from_telegram"
}
```

**Параметры:**
- `file_id` (string, обязательный): File_id стикера

**Ответ (200 OK):**
```json
{
  "message": "Стикер успешно удален из набора!"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при удалении стикера из набора

#### POST /set_sticker_position_in_set

Изменяет позицию стикера в наборе.

**Тело запроса:**
```json
{
  "sticker_file_id": "file_id_from_telegram",
  "position": 0
}
```

**Параметры:**
- `sticker_file_id` (string, обязательный): File_id стикера
- `position` (integer, обязательный): Новая позиция стикера (0 - первая позиция)

**Ответ (200 OK):**
```json
{
  "message": "Позиция стикера успешно изменена!"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при изменении позиции стикера

#### POST /delete_sticker_set

Удаляет набор стикеров.

**Тело запроса:**
```json
{
  "sticker_set_name": "example_set_by_bot_name"
}
```

**Параметры:**
- `sticker_set_name` (string, обязательный): Полное название набора стикеров (включая суффикс _by_bot)

**Ответ (200 OK):**
```json
{
  "message": "Набор стикеров успешно удален!"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при удалении набора стикеров

#### POST /create_sticker_set_db

Создает запись о стикерпаке в базе данных.

**Тело запроса:**
```json
{
  "user_id": 123456789,
  "sticker_set_name": "example_set_by_bot_name"
}
```

**Параметры:**
- `user_id` (integer, обязательный): ID пользователя
- `sticker_set_name` (string, обязательный): Полное название набора стикеров (включая суффикс _by_bot)

**Ответ (201 Created):**
```json
{
  "id": 1,
  "set_name": "example_set_by_bot_name",
  "user_id": 123456789
}
```

**Ошибки:**
- 404 Not Found: Пользователь не найден
- 400 Bad Request: Ошибка валидации
- 500 Internal Server Error: Внутренняя ошибка сервера

#### GET /user_sticker_sets/{user_id}

Возвращает список названий всех стикерпаков пользователя.

**Параметры пути:**
- `user_id` (integer, обязательный): ID пользователя

**Ответ (200 OK):**
```json
[
  {
    "id": 1,
    "set_name": "example_set_by_bot_name",
    "user_id": 123456789
  }
]
```

**Ошибки:**
- 404 Not Found: Пользователь не найден
- 500 Internal Server Error: Внутренняя ошибка сервера

### Прокси для Telegram API

#### GET /stickers/packs/{pack_name}

Получает информацию о стикерпаке из Telegram.

**Параметры пути:**
- `pack_name` (string, обязательный): Название стикерпака

**Ответ (200 OK):**
```json
{
  "name": "example_set_by_bot_name",
  "title": "Example Sticker Set",
  "sticker_type": "regular",
  "thumbnail_url": "http://localhost:8001/stickers/proxy/sticker/file_id_from_telegram",
  "share_url": "https://t.me/addstickers/example_set_by_bot_name",
  "stickers": [
    {
      "file_id": "file_id_from_telegram",
      "emoji": "😀",
      "position": 0,
      "file_url": "http://localhost:8001/stickers/proxy/sticker/file_id_from_telegram"
    }
  ]
}
```

#### GET /stickers/proxy/sticker/{file_id}

Прокси для получения изображения стикера без раскрытия токена бота.

**Параметры пути:**
- `file_id` (string, обязательный): File ID стикера

**Ответ (200 OK):**
Изображение стикера в формате WebP с заголовками:
- Content-Type: image/webp
- Content-Disposition: inline
- Cache-Control: public, max-age=86400

**Ошибки:**
- 404 Not Found: Стикер не найден
- 500 Internal Server Error: Ошибка при получении стикера

#### POST /stickers/test/upload

Тестовый эндпоинт для загрузки изображения в Telegram.

**Форма запроса:**
- `user_id` (integer, обязательный): Telegram ID пользователя
- `image_url` (string, обязательный): URL изображения для загрузки

**Ответ (200 OK):**
```json
{
  "success": true,
  "file_id": "file_id_from_telegram",
  "file_url": "http://localhost:8001/stickers/proxy/sticker/file_id_from_telegram"
}
```

**Ошибки:**
- 500 Internal Server Error: Ошибка при загрузке изображения

## Модели данных

### UserBase
```json
{
  "user_id": 123456789,
  "username": "example_user",
  "chat_id": 123456789,
  "balance": 0
}
```

### UserCreate
```json
{
  "user_id": 123456789,
  "username": "example_user",
  "chat_id": 123456789,
  "balance": 0
}
```

### ImageBase
```json
{
  "id": 1,
  "link": "file_id_from_telegram",
  "prompt_id": "prompt_id_from_comfyui",
  "status": "COMPLETED",
  "created_at": "2025-03-12T12:00:00",
  "sticker_set_id": null
}
```

### StickerUploadRequest
```json
{
  "user_id": 123456789,
  "link": "https://example.com/image.png"
}
```

### StickerSetRequest
```json
{
  "user_id": 123456789,
  "sticker_set_name": "example_set",
  "title": "Example Sticker Set",
  "file_id": "file_id_from_telegram",
  "emojis": "😀",
  "is_animated": false,
  "is_video": false
}
```

### StickerFileID
```json
{
  "file_id": "file_id_from_telegram"
}
```

### StickerSetPosition
```json
{
  "sticker_file_id": "file_id_from_telegram",
  "position": 0
}
```

### StickerSetName
```json
{
  "sticker_set_name": "example_set_by_bot_name"
}
```

### GenerateImageRequest
```json
{
  "tag": "image_generation",
  "user_id": 123456789,
  "workflow": {
    // Объект workflow для ComfyUI
  }
}
```

### CreateStickerSetDBRequest
```json
{
  "user_id": 123456789,
  "sticker_set_name": "example_set_by_bot_name"
}
```

### StickerSetResponse
```json
{
  "id": 1,
  "set_name": "example_set_by_bot_name",
  "user_id": 123456789
}
```

### TaskPosition
```json
{
  "task_id": 123,
  "status": "PENDING",
  "queue_position": 3
}
```

### PendingTask
```json
{
  "task_id": 123,
  "prompt_id": "prompt_id_from_comfyui",
  "status": "PENDING",
  "created_at": "2025-03-13T11:15:00",
  "queue_position": 3,
  "updated_at": "2025-03-13T11:20:00"
}