Image Generation

Basic usage of the image generation API.

Simple Generation

import { NovelAI } from 'novelai-sdk-unofficial';
import { writeFileSync } from 'fs';

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

const images = await client.image.generate({
  prompt: '1girl, cat ears, masterpiece, best quality',
});

writeFileSync('output.png', images[0]);

With Options

const images = await client.image.generate({
  prompt: '1girl, cat ears, masterpiece, best quality',
  model: 'nai-diffusion-4-5-full',
  size: 'portrait',
  steps: 23,
  scale: 5.0,
  sampler: 'k_euler_ancestral',
  seed: 12345,
});

Parameters

Parameter	Type	Default	Description
prompt	string	required	Text description of the image
model	ImageModel	'nai-diffusion-4-5-full'	Model to use
size	ImageSize	'portrait'	Size preset or [width, height]
negativePrompt	string	''	What to avoid in the image
quality	boolean	true	Auto-append quality tags
ucPreset	UCPreset	'light'	Undesired content preset
steps	number	23	Generation steps (1-50)
scale	number	5.0	CFG scale (0-10)
sampler	Sampler	'k_euler_ancestral'	Sampling method
noiseSchedule	NoiseSchedule	'karras'	Noise schedule
seed	number	random	Random seed (0-999999999)
nSamples	number	1	Number of images (1-8)
cfgRescale	number	0	CFG rescale (0-1)
varietyBoost	boolean	false	Enable variety boost

Quality Tags

When quality: true (default), the SDK automatically appends quality-enhancing tags to your prompt.

// With quality tags (default)
const images = await client.image.generate({
  prompt: '1girl',
  quality: true,
});

// Without quality tags
const images = await client.image.generate({
  prompt: '1girl',
  quality: false,
});

Negative Prompt

Use negativePrompt to specify what to avoid:

const images = await client.image.generate({
  prompt: '1girl, standing',
  negativePrompt: 'bad anatomy, blurry',
});

UC Presets

The ucPreset parameter adds predefined negative prompts:

• 'none' - No preset
• 'light' - Light filtering (default)
• 'strong' - Strong filtering
• 'furry_focus' - Furry-focused filtering
• 'human_focus' - Human-focused filtering

const images = await client.image.generate({
  prompt: '1girl',
  ucPreset: 'strong',
});

Batch Generation

Generate multiple images at once:

const images = await client.image.generate({
  prompt: '1girl, various poses',
  nSamples: 4,
});

images.forEach((img, i) => {
  writeFileSync(`output_${i}.png`, img);
});

Reproducible Results

Use a fixed seed for reproducible results:

const images = await client.image.generate({
  prompt: '1girl',
  seed: 42,
});

SDK Internal Processing

When using the High-Level API, the SDK automatically handles the following:

Auto-added Parameters

The SDK automatically sets these API parameters for optimal compatibility:

Parameter	Value	Description
use_new_shared_trial	true	Enable new shared trial mode
params_version	3	API parameter version
prefer_brownian	true	Use Brownian motion noise
legacy	false	Disable legacy mode
legacy_uc	false	Disable legacy UC mode
legacy_v3_extend	false	Disable V3 extend mode

V4+ Model Prompt Structure

For V4 and V4.5 models, the SDK automatically converts prompts to v4_prompt structure:

// User input
{
  prompt: '1girl, cat ears',
  quality: true,
}

// SDK converts to
{
  input: '1girl, cat ears',
  v4_prompt: {
    caption: {
      base_caption: '1girl, cat ears, very aesthetic, masterpiece, no text',
      char_captions: []
    },
    use_coords: false,
    use_order: true
  }
}

UC Preset Mapping

The ucPreset string is automatically mapped to API numeric values:

Preset	API Value
'strong'	0
'light'	1
'furry_focus'	2
'human_focus'	3
'none'	4