Клиент FusionBrain API

Клиент на Python для взаимодействия с API FusionBrain, предназначенный для генерации изображений на основе текстовых описаний. Проект организован модульно, с разделением логики на взаимодействие с API, обработку изображений и управление конфигурацией, что обеспечивает удобство поддержки и масштабируемость.

Содержание

• Возможности
• Требования
• Установка
• Настройка
• Использование
• Деплой в Docker
• Структура проекта
• Логирование
• Обработка ошибок
• Как внести вклад
• Лицензия

Возможности

• Взаимодействие с API: Запрос идентификаторов pipeline, инициирование генерации изображений и проверка статуса генерации.
• Обработка изображений: Сохранение сгенерированных изображений из URL или base64-строк на локальную файловую систему.
• Управление конфигурацией: Загрузка настроек (ключей API, текстового описания, размеров изображений) из переменных окружения.
• Надежная обработка ошибок: Обработка сетевых проблем, некорректных ответов API и таймаутов с подробным логированием.
• Модульный дизайн: Разделение логики на модули для упрощения поддержки и тестирования.

Требования

• Python 3.8 или выше
• Необходимые Python-библиотеки:
  • requests
  • python-dotenv
• Для деплоя в Docker:
  • Docker
  • Docker Compose

Установка

Локальная установка

1. Клонируйте репозиторий:

   git clone https://github.com/Vgoroveckiy/Kandinsky_api.git
   cd Kandinsky_api

2. Создайте и активируйте виртуальное окружение:

   python -m venv venv
   source venv/bin/activate  # На Windows: venv\Scripts\activate

3. Установите зависимости:

   pip install -r requirements.txt

Установка через Docker

См. раздел Деплой в Docker

Настройка

Клиент использует переменные окружения для настройки доступа к API и параметров генерации. Создайте файл .env в корневой папке проекта со следующей структурой:

FUSIONBRAIN_API_KEY=ваш_ключ_api
FUSIONBRAIN_SECRET_KEY=ваш_секретный_ключ
FUSIONBRAIN_DEFAULT_PROMPT="Красивый закат на морском побережье"
FUSIONBRAIN_DEFAULT_WIDTH=512
FUSIONBRAIN_DEFAULT_HEIGHT=512
FUSIONBRAIN_DEFAULT_IMAGES=1

• FUSIONBRAIN_API_KEY и FUSIONBRAIN_SECRET_KEY: Обязательные ключи для доступа к API FusionBrain.
• FUSIONBRAIN_DEFAULT_PROMPT: Необязательное текстовое описание для генерации (по умолчанию: "Красивый закат на морском побережье").
• FUSIONBRAIN_DEFAULT_WIDTH и FUSIONBRAIN_DEFAULT_HEIGHT: Необязательные размеры изображения в пикселях (по умолчанию: 512x512).
• FUSIONBRAIN_DEFAULT_IMAGES: Необязательное количество изображений для генерации (по умолчанию: 1).

Добавьте файл .env в .gitignore, чтобы избежать утечки конфиденциальных данных.

Использование

Запустите скрипт для генерации и сохранения изображений с помощью API FusionBrain. Скрипт выполняет следующие шаги:

1. Загружает конфигурацию из файла .env.
2. Запрашивает идентификатор pipeline из API.
3. Инициирует генерацию изображений с указанным описанием и параметрами.
4. Периодически проверяет статус генерации.
5. Сохраняет сгенерированные изображения в папку output/.

Пример

python app.py

Это сгенерирует изображения на основе настроек в .env и сохранит их как generated_image_1.png, generated_image_2.png и т.д. в папке output/.

Пример вывода

2025-04-17 10:00:00,123 - INFO - Инициализация ConfigManager
2025-04-17 10:00:00,124 - INFO - Конфигурация успешно проверена
2025-04-17 10:00:00,125 - INFO - FusionBrainAPI инициализирован с URL: https://api-key.fusionbrain.ai/
2025-04-17 10:00:00,126 - INFO - Запрос идентификатора pipeline с https://api-key.fusionbrain.ai/key/api/v1/pipelines
2025-04-17 10:00:00,789 - INFO - Идентификатор pipeline успешно получен: pipeline_123
2025-04-17 10:00:00,790 - INFO - Инициирование генерации изображения с описанием: Красивый закат на морском побережье, pipeline: pipeline_123, изображения: 1, ширина: 512, высота: 512
2025-04-17 10:00:01,456 - INFO - Генерация изображения инициирована, UUID: uuid_456
2025-04-17 10:00:01,457 - INFO - Проверка статуса генерации для UUID: uuid_456
2025-04-17 10:00:06,789 - INFO - Генерация завершена, найдено 1 изображение для UUID: uuid_456
2025-04-17 10:00:06,790 - INFO - Создана папка output
2025-04-17 10:00:06,791 - INFO - Сохранение изображения в output/generated_image_1.png
2025-04-17 10:00:06,792 - INFO - Изображение в формате base64 декодировано и сохранено в output/generated_image_1.png

Если изображения не были сгенерированы, выводится предупреждение в логах и сообщение об ошибке в консоль.

Деплой в Docker

Приложение может быть развернуто в Docker-контейнере. Для этого:

1. Убедитесь, что у вас установлены Docker и Docker Compose
2. Соберите образ:

   docker build -t kandinsky-api:latest .

3. Запустите контейнер:

   docker-compose up -d

4. Приложение будет доступно по адресу: http://localhost:5000

Конфигурация

• Порт приложения: 5000 (можно изменить в docker-compose.yml)
• Переменные окружения загружаются из .env файла

Структура проекта

Проект разделен на несколько модулей:

• ConfigManager: Управляет конфигурацией, загружая и проверяя переменные окружения.
• FusionBrainAPI: Отвечает за взаимодействие с API FusionBrain.
• ImageHandler: Обрабатывает и сохраняет сгенерированные изображения.

Структура файлов

Kandinsky_api/
├── .dockerignore
├── .gitignore
├── app.py                # Основной скрипт приложения
├── docker-compose.yml    # Конфигурация Docker Compose
├── Dockerfile            # Конфигурация Docker
├── requirements.txt      # Зависимости Python
├── README.md             # Документация (этот файл)
├── generated_images/     # Папка для сгенерированных изображений
└── templates/            # HTML шаблоны
    └── index.html

Логирование

Клиент использует модуль logging для вывода подробных логов операций и ошибок. Логи содержат метки времени, уровень лога и сообщения. Примеры уровней логов:

• INFO: Успешные операции (например, получение pipeline, сохранение изображения).
• WARNING: Некритические проблемы (например, отсутствие файлов в ответе API).
• ERROR: Критические сбои (например, сетевые ошибки, некорректные ответы API).
• DEBUG: Подробная информация о повторах в check_generation.

Логи по умолчанию выводятся в консоль. Для записи логов в файл измените конфигурацию логирования в app.py.

Обработка ошибок

Клиент обрабатывает следующие ошибки:

• Сетевые ошибки: Ловятся как requests.exceptions.RequestException (например, проблемы с подключением, таймауты).
• Ошибки API: HTTP-статусы, отличные от 200/201, или неожиданные форматы ответа.
• Ошибки конфигурации: Отсутствие или некорректность ключей API.
• Ошибки обработки изображений: Неподдерживаемые форматы данных или сбои при скачивании/декодировании.
• Таймауты: Генерация не завершена в течение заданного числа попыток.

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

Как внести вклад

Приветствуются любые улучшения! Чтобы внести вклад:

1. Сделайте форк репозитория.
2. Создайте ветку для новой функциональности (git checkout -b feature/ваша-функция).
3. Внесите изменения (git commit -m "Добавлена ваша функция").
4. Отправьте ветку в репозиторий (git push origin feature/ваша-функция).
5. Откройте pull request.

Добавляйте тесты и обновляйте документацию при необходимости.

Лицензия

Проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.