novelai-sdk-unofficial / ImageGeneration

Class: ImageGeneration

Defined in: src/client.ts:85

High-level image generation interface

Provides user-friendly methods for image generation with automatic parameter validation and processing.

Constructors

Constructor

new ImageGeneration(client): ImageGeneration

Defined in: src/client.ts:88

Parameters

client

NovelAI

Returns

ImageGeneration

Methods

augmentImage()

augmentImage(params): Promise<Buffer<ArrayBufferLike>[]>

Defined in: src/client.ts:221

Augment an image using Director Tools

Supports various augmentation types like background removal, line art extraction, sketch conversion, and colorization.

Parameters

params

Augmentation parameters

defry?

number = ...

Defry level (0-5)

height

number = ...

Output height (must match actual image height)

image

string | ArrayBuffer | Buffer<ArrayBufferLike> = ...

Image to augment - supports Buffer, base64 string, or ArrayBuffer

prompt?

string = ...

Prompt for augmentation (used by some types like colorize)

type

"bg-removal" | "lineart" | "sketch" | "colorize" | "emotion" | "declutter" = ...

Augmentation type

width

number = ...

Output width (must match actual image width)

Returns

Promise<Buffer<ArrayBufferLike>[]>

Array of augmented image buffers

Throws

ZodError if parameters fail validation

Example

const client = new NovelAI({ apiKey: 'your-api-key' });

// Background removal
const images = await client.image.augmentImage({
  image: imageBuffer,
  type: 'bg-removal',
  width: 1024,
  height: 1024,
});

// Colorization with prompt
const colorized = await client.image.augmentImage({
  image: sketchBuffer,
  type: 'colorize',
  width: 1024,
  height: 1024,
  prompt: 'vibrant colors, detailed shading',
});

---

generate()

generate(params): Promise<Buffer<ArrayBufferLike>[]>

Defined in: src/client.ts:125

Generate images using the NovelAI API

This method provides a user-friendly interface with:

• Automatic parameter validation via Zod schemas
• Quality tags appending when quality=true
• UC preset tags appending
• Size preset to dimensions conversion
• V4 prompt structure creation for V4+ models

Parameters

params

User-friendly generation parameters

cfgRescale?

number = ...

characterReferences?

object[] = ...

characters?

object[] = ...

controlnet?

{ images: object[]; strength?: number; } = ...

controlnet.images

object[] = ...

controlnet.strength?

number = ...

i2i?

{ image: string | ArrayBuffer | Buffer<ArrayBufferLike>; mask?: string | ArrayBuffer | Buffer<ArrayBufferLike>; noise?: number; strength?: number; } = ...

i2i.image

string | ArrayBuffer | Buffer<ArrayBufferLike> = ...

i2i.mask?

string | ArrayBuffer | Buffer<ArrayBufferLike> = ...

i2i.noise?

number = ...

i2i.strength?

number = ...

imageFormat?

"webp" | "png" = ...

model?

"nai-diffusion-4-5-full" | "nai-diffusion-4-5-curated" | "nai-diffusion-4-full" | "nai-diffusion-4-curated" | "nai-diffusion-3" | "nai-diffusion-3-furry" = ...

negativePrompt?

string = ...

noiseSchedule?

"karras" | "exponential" | "polyexponential" = ...

nSamples?

number = ...

prompt

string = ...

quality?

boolean = ...

sampler?

"k_euler" | "k_euler_ancestral" | "k_dpm_2" | "k_dpm_2_ancestral" | "k_dpmpp_2m" | "k_dpmpp_2s_ancestral" | "k_dpmpp_sde" | "ddim" = ...

scale?

number = ...

seed?

number = ...

size?

[number, number] | "portrait" | "landscape" | "square" | "large_portrait" | "large_landscape" = ...

steps?

number = ...

ucPreset?

"light" | "strong" | "furry_focus" | "human_focus" | "none" = ...

varietyBoost?

boolean = ...

Returns

Promise<Buffer<ArrayBufferLike>[]>

Array of image buffers

Throws

ZodError if parameters fail validation

Example

const client = new NovelAI({ apiKey: 'your-api-key' });

// Simple generation
const images = await client.image.generate({
  prompt: 'a beautiful landscape',
});

// With options
const images = await client.image.generate({
  prompt: 'a beautiful landscape',
  model: 'nai-diffusion-4-5-full',
  size: 'landscape',
  steps: 28,
  scale: 5.0,
});

---

generateStream()

generateStream(params, signal?): AsyncGenerator<ImageStreamChunk, void, unknown>

Defined in: src/client.ts:175

Generate images with streaming progress updates

Returns an async generator that yields ImageStreamChunk objects containing intermediate and final images.

Parameters

params

User-friendly generation parameters with streaming

cfgRescale?

number = ...

characterReferences?

object[] = ...

characters?

object[] = ...

controlnet?

{ images: object[]; strength?: number; } = ...

controlnet.images

object[] = ...

controlnet.strength?

number = ...

i2i?

{ image: string | ArrayBuffer | Buffer<ArrayBufferLike>; mask?: string | ArrayBuffer | Buffer<ArrayBufferLike>; noise?: number; strength?: number; } = ...

i2i.image

string | ArrayBuffer | Buffer<ArrayBufferLike> = ...

i2i.mask?

string | ArrayBuffer | Buffer<ArrayBufferLike> = ...

i2i.noise?

number = ...

i2i.strength?

number = ...

imageFormat?

"webp" | "png" = ...

model?

"nai-diffusion-4-5-full" | "nai-diffusion-4-5-curated" | "nai-diffusion-4-full" | "nai-diffusion-4-curated" | "nai-diffusion-3" | "nai-diffusion-3-furry" = ...

negativePrompt?

string = ...

noiseSchedule?

"karras" | "exponential" | "polyexponential" = ...

nSamples?

number = ...

prompt

string = ...

quality?

boolean = ...

sampler?

"k_euler" | "k_euler_ancestral" | "k_dpm_2" | "k_dpm_2_ancestral" | "k_dpmpp_2m" | "k_dpmpp_2s_ancestral" | "k_dpmpp_sde" | "ddim" = ...

scale?

number = ...

seed?

number = ...

size?

[number, number] | "portrait" | "landscape" | "square" | "large_portrait" | "large_landscape" = ...

steps?

number = ...

stream?

"msgpack" | "sse" = ...

ucPreset?

"light" | "strong" | "furry_focus" | "human_focus" | "none" = ...

varietyBoost?

boolean = ...

signal?

AbortSignal

Optional AbortSignal for cancellation

Returns

AsyncGenerator<ImageStreamChunk, void, unknown>

Yields

ImageStreamChunk objects with progress and image data

Example

const client = new NovelAI({ apiKey: 'your-api-key' });
const controller = new AbortController();

const stream = client.image.generateStream({
  prompt: 'a beautiful landscape',
  steps: 28,
}, controller.signal);

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  for await (const chunk of stream) {
    if (chunk.event_type === 'intermediate') {
      console.log(`Step ${chunk.step_ix}: sigma=${chunk.sigma}`);
    } else if (chunk.event_type === 'final') {
      console.log('Final image received');
      const imageBuffer = Buffer.from(chunk.image, 'base64');
    }
  }
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Generation cancelled');
  }
}

---

suggestTags()

suggestTags(params): Promise<TagSuggestion[]>

Defined in: src/client.ts:283

Get tag suggestions for image generation prompts

Returns an array of suggested tags based on the input prompt. Useful for auto-completion and discovering related tags.

Parameters

params

Tag suggestion parameters (can be just a string for simple usage)

lang?

"en" | "jp" = ...

Language for suggestions

model?

"nai-diffusion-4-5-full" | "nai-diffusion-4-5-curated" | "nai-diffusion-4-full" | "nai-diffusion-4-curated" | "nai-diffusion-3" | "nai-diffusion-3-furry" = ...

Image model to use for suggestions

prompt

string = ...

Incomplete tag query to get suggestions for

Returns

Promise<TagSuggestion[]>

Array of tag suggestions with confidence scores

Throws

ZodError if parameters fail validation

Example

const client = new NovelAI({ apiKey: 'your-api-key' });

// Simple usage - just pass the prompt string
const tags = await client.image.suggestTags({ prompt: '1girl, blue' });

// With options
const tags = await client.image.suggestTags({
  prompt: '1girl, blue',
  model: 'nai-diffusion-4-5-full',
  lang: 'en',
});

for (const tag of tags) {
  console.log(`${tag.tag}: ${tag.confidence}`);
}