@brojs/stable-diffusion

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

Установка

``bash
npm install @brojs/stable-diffusion
`

Требования

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

Возможности

$3

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

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

$3

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

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

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

$3

`typescript
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);
});
`

$3

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

`typescript
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);
`

$3

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

`typescript
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 - обрабатывает всё изображение целиком (рекомендуется для сохранения контекста)

$3

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

`typescript
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);
`

$3

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

`typescript
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}));
`

$3

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

`typescript
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);
`

$3

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

`typescript
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);
}
`

$3

`typescript
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();
`

$3

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

`typescript
// По 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

$3

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

Параметры:
- 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 - путь к файлу

$3

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

#### Методы

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

Типы

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

`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.

$3

`bash
cd packages/stable-diffusion
npx tsx check.ts
`

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

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

Лицензия

ISC