@brojs/stable-diffusion

TypeScript библиотека для работы с Stable Diffusion WebUI API.

Установка

npm install @brojs/stable-diffusion

Требования

• Запущенный Stable Diffusion WebUI с включенным API
• По умолчанию подключается к http://127.0.0.1:7860
• Можно изменить через переменную окружения STABLE_DIFFUSION_URL

Возможности

✅ Реализовано

• Text-to-Image (txt2img) - генерация изображений из текста
• Image-to-Image (img2img) - модификация существующих изображений
• Inpainting - замена частей изображения по маске
• Upscale - улучшение качества и увеличение разрешения
• Interrogate - получение текстового описания из изображения
• Batch генерация - создание нескольких вариантов
• Потоковая генерация - получение изображений по мере готовности

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

Простой пример (Text-to-Image)

import { generateImage } from '@brojs/stable-diffusion';

const imagePath = await generateImage({
  prompt: 'a beautiful sunset over the ocean, golden hour'
});

console.log('Изображение сохранено:', imagePath);

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

import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

const generator = new StableDiffusionGenerator({
  prompt: 'beautiful landscape',
  steps: 30,
  cfg_scale: 8.0,
  width: 768,
  height: 512
});

// Генерация нескольких изображений
const results = await generator.generate({
  batch_size: 4
});

results.forEach((result, i) => {
  console.log(`${i + 1}. ${result.filePath}`);
  console.log(`   Seed: ${result.seed}`);
  console.log(`   Время: ${result.generationTime}ms`);
});

Feature 1: Image-to-Image

Модификация существующего изображения:

import fs from 'fs';
import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

// Загружаем изображение и конвертируем в base64
const imageBuffer = fs.readFileSync('input.jpg');
const base64Image = imageBuffer.toString('base64');

const generator = new StableDiffusionGenerator({
  prompt: 'same image but in anime style'
});

const results = await generator.img2img({
  init_images: [base64Image],
  denoising_strength: 0.75, // 0.0 = без изменений, 1.0 = полная перегенерация
  steps: 40
});

console.log('Результат:', results[0].filePath);

Feature 1: Inpainting

Замена части изображения по маске:

import fs from 'fs';
import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

const imageBuffer = fs.readFileSync('input.jpg');
const maskBuffer = fs.readFileSync('mask.png'); // Белые области = редактируемые

const base64Image = imageBuffer.toString('base64');
const base64Mask = maskBuffer.toString('base64');

const generator = new StableDiffusionGenerator({
  prompt: 'a red apple on the table'
});

const results = await generator.inpaint({
  init_images: [base64Image],
  mask: base64Mask,
  denoising_strength: 0.75,  // 0.75 сохраняет контекст, 1.0 = полная перегенерация
  inpainting_fill: 1,        // 1 = original (сохраняет оригинал за маской)
  inpaint_full_res: false    // Обработка всего изображения
});

console.log('Inpainting результат:', results[0].filePath);

Важные параметры:

• denoising_strength: 0.75 - сохраняет контекст исходного изображения (мебель, фон). При 1.0 полностью игнорирует оригинал.
• inpainting_fill: 1 - заполняет область маски оригинальным контентом перед обработкой (лучше сохраняет детали)
• inpaint_full_res: false - обрабатывает всё изображение целиком (рекомендуется для сохранения контекста)

Feature 2: Upscale (одиночное изображение)

Увеличение разрешения и улучшение качества:

import fs from 'fs';
import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

const imageBuffer = fs.readFileSync('low_res.jpg');
const base64Image = imageBuffer.toString('base64');

const generator = new StableDiffusionGenerator({
  prompt: '' // Не используется для upscale
});

const result = await generator.upscale({
  image: base64Image,
  upscaling_resize: 4, // Увеличить в 4 раза
  upscaler_1: 'R-ESRGAN 4x+', // Модель upscaler'а
  gfpgan_visibility: 1.0 // Улучшение лиц
});

console.log('Upscaled:', result.filePath);

Feature 2: Upscale Batch (пакетная обработка)

Обработка нескольких изображений:

import fs from 'fs';
import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

const images = ['img1.jpg', 'img2.jpg', 'img3.jpg'].map(file => {
  const buffer = fs.readFileSync(file);
  return buffer.toString('base64');
});

const generator = new StableDiffusionGenerator({
  prompt: ''
});

const results = await generator.upscaleBatch({
  images: images,
  upscaling_resize: 2,
  upscaler_1: 'R-ESRGAN 4x+'
});

console.log(`Обработано ${results.length} изображений`);
results.forEach((r, i) => console.log(`${i + 1}. ${r.filePath}`));

Feature 3: Interrogate

Получение текстового описания из изображения:

import fs from 'fs';
import { StableDiffusionGenerator } from '@brojs/stable-diffusion';

const imageBuffer = fs.readFileSync('photo.jpg');
const base64Image = imageBuffer.toString('base64');

const generator = new StableDiffusionGenerator({
  prompt: ''
});

// CLIP interrogator - общее описание
const clipPrompt = await generator.interrogate({
  image: base64Image,
  model: 'clip'
});

console.log('CLIP описание:', clipPrompt);

// DeepDanbooru - для anime/manga (теги)
const tags = await generator.interrogate({
  image: base64Image,
  model: 'deepdanbooru'
});

console.log('Теги:', tags);

Потоковая генерация

Получение изображений по мере готовности:

const generator = new StableDiffusionGenerator({
  prompt: 'cosmic nebula, space art',
  batch_size: 3
});

for await (const result of generator.generateStream()) {
  console.log('Новое изображение готово:', result.filePath);
  console.log('Seed:', result.seed);
  console.log('Время генерации:', result.generationTime, 'ms');
  
  // Можно сразу обрабатывать изображение
  await processImage(result.filePath);
}

Временное переопределение параметров

const generator = new StableDiffusionGenerator({
  prompt: 'default prompt',
  steps: 30,
  cfg_scale: 8.0
});

// Генерация с временными параметрами (не меняет конфиг класса)
const results = await generator.generate({
  prompt: 'temporary prompt',
  steps: 50
});

// Следующий вызов использует оригинальные параметры
const results2 = await generator.generate();

Кастомные имена файлов

По умолчанию файлы именуются с использованием UUID. Можно переопределить функцию генерации имен:

// По timestamp
const generator = new StableDiffusionGenerator({
  prompt: 'beautiful landscape',
  filenameGenerator: () => `img-${Date.now()}`
});

// По счетчику
let counter = 0;
const generator2 = new StableDiffusionGenerator({
  prompt: 'cat portrait',
  filenameGenerator: () => `image-${++counter}`
});

// По seed (если нужно воспроизводимое именование)
const generator3 = new StableDiffusionGenerator({
  prompt: 'test',
  seed: 12345,
  filenameGenerator: () => `seed-12345`
});

// Результаты: img-1729260000000.png, image-1.png, seed-12345.png

Примечание: Расширение .png добавляется автоматически и не может быть изменено.

API

generateImage(config)

Простая функция для генерации одного изображения.

Параметры:

• prompt (string, обязательный) - текстовое описание
• outputDir (string) - директория для сохранения
• negative_prompt (string) - что НЕ должно быть на изображении
• seed (number) - seed для воспроизводимости (-1 = случайный)
• steps (number) - количество шагов диффузии (по умолчанию: 30)
• cfg_scale (number) - насколько строго следовать промпту (по умолчанию: 8.0)
• width (number) - ширина в пикселях (по умолчанию: 768)
• height (number) - высота в пикселях (по умолчанию: 512)
• sampler_name (string) - алгоритм генерации (по умолчанию: 'DPM++ SDE Karras')
• batch_size (number) - количество изображений (по умолчанию: 1)
• restore_faces (boolean) - улучшение лиц (по умолчанию: true)
• filenameGenerator (function) - функция генерации имени файла без расширения (по умолчанию: UUID v4)

Возвращает: Promise<string> - путь к файлу

StableDiffusionGenerator

Класс с расширенными возможностями.

Методы

• generate(overrideConfig?) - генерация всех изображений сразу
• generateStream(overrideConfig?) - потоковая генерация
• img2img(config) - модификация изображения
• inpaint(config) - inpainting по маске
• upscale(options) - улучшение одного изображения
• upscaleBatch(options) - улучшение нескольких изображений
• interrogate(options) - получение промпта из изображения
• setConfig(config) - обновление конфигурации
• setConfigValue(key, value) - установка одного параметра
• getConfig() - получение текущей конфигурации

Типы

Все интерфейсы экспортируются и доступны для TypeScript:

import type {
  Txt2ImgConfig,
  GenerationResult,
  UpscaleOptions,
  UpscaleBatchOptions,
  UpscaleResult,
  InterrogateOptions
} from '@brojs/stable-diffusion';

Переменные окружения

• STABLE_DIFFUSION_URL - URL к Stable Diffusion WebUI API (по умолчанию: http://127.0.0.1:7860)

Тестирование

Библиотека включает комплексный тест всех возможностей в файле check.ts.

Запуск тестов

cd packages/stable-diffusion
npx tsx check.ts

Тест автоматически:

• ✅ Проверяет все методы библиотеки
• 📸 Генерирует реальные изображения
• 📝 Создает подробный Markdown отчет TEST-REPORT.md
• ⏱️ Замеряет время выполнения
• 📊 Формирует таблицы с параметрами

Подробнее см. TESTING.md

Лицензия

ISC