StickerAI-Front/API_DOCUMENTATION.md

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

## Обзор

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

Базовый URL: `https://stickerserver.gymnasticstuff.uk`

## Эндпоинты

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

#### GET /health

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

**Ответ (200 OK):**
```
"string"
```

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

#### 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
}
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### 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: Пользователь не найден
- 422 Validation Error: Ошибка валидации данных

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

#### POST /generate_image

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

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### GET /user_pending_tasks/{user_id}

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### GET /task_position/{task_id}

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation 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: Пользователь не найден
- 422 Validation Error: Ошибка валидации данных

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

#### POST /upload_sticker

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

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

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

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

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### 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):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### POST /add_sticker_to_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):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### GET /check_sticker_set_name/{sticker_set_name}

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### POST /delete_sticker_from_set

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

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### POST /set_sticker_position_in_set

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

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### POST /delete_sticker_set

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

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation 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
}
```

**Ошибки:**
- 422 Validation 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
  }
]
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

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

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

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

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

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

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

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

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

#### POST /stickers/test/upload

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

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

**Ответ (200 OK):**
```
"string"
```

**Ошибки:**
- 422 Validation Error: Ошибка валидации данных

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

### UserBase
```json
{
  "user_id": 1,
  "username": "john_doe",
  "chat_id": 123456789,
  "balance": 100
}
```

### UserCreate
```json
{
  "user_id": 1,
  "username": "john_doe",
  "chat_id": 123456789,
  "balance": 100
}
```

### ImageBase
```json
{
  "id": 0,
  "link": "string",
  "prompt_id": "string",
  "status": "string",
  "created_at": "2025-03-19T12:15:53.248Z",
  "sticker_set_id": 0
}
```

### StickerUploadRequest
```json
{
  "user_id": 0,
  "link": "string"
}
```

### StickerSetRequest
```json
{
  "user_id": 0,
  "sticker_set_name": "string",
  "title": "string",
  "file_id": "string",
  "emojis": "string",
  "is_animated": false,
  "is_video": false
}
```

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

### StickerSetPosition
```json
{
  "file_id": "string",
  "position": 0
}
```

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

### GenerateImageRequest
```json
{
  "tag": "image_generation",
  "user_id": 0,
  "workflow": {}
}
```

### CreateStickerSetDBRequest
```json
{
  "user_id": 0,
  "sticker_set_name": "string"
}
```

### StickerSetResponse
```json
{
  "id": 0,
  "set_name": "string",
  "user_id": 0
}
```

### HTTPValidationError
```json
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

### ValidationError
```json
{
  "loc": [
    "string",
    0
  ],
  "msg": "string",
  "type": "string"
}