Character Reference

Character Reference allows you to maintain consistent character appearances across multiple generations using reference images.

WARNING

Character Reference is only available for V4.5 models (nai-diffusion-4-5-full and nai-diffusion-4-5-curated).

Basic Usage

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

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

// Load reference image
const referenceImage = readFileSync('reference.png');

const images = await client.image.generate({
  prompt: '1girl, standing in a garden',
  model: 'nai-diffusion-4-5-full',
  characterReferences: [
    {
      image: referenceImage,
      type: 'character',
      fidelity: 0.75,
    },
  ],
});

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

Parameters

Parameter	Type	Default	Description
image	ImageInput	required	Reference image (Buffer, base64 string, or ArrayBuffer)
type	'character' | 'character&style'	'character&style'	Reference type
fidelity	number	0.75	How closely to match the reference (0-1)

Reference Types

Character Only

Transfers only the character's appearance:

characterReferences: [
  {
    image: referenceImage,
    type: 'character',
    fidelity: 0.75,
  },
]

Character & Style

Transfers both character appearance and artistic style:

characterReferences: [
  {
    image: referenceImage,
    type: 'character&style',
    fidelity: 0.75,
  },
]

Fidelity

The fidelity parameter controls how closely the output matches the reference:

• 0.0 - Minimal influence from reference
• 0.5 - Balanced influence
• 0.75 - Strong influence (default)
• 1.0 - Maximum influence

// Lower fidelity - more creative freedom
characterReferences: [{ image: ref, fidelity: 0.3 }]

// Higher fidelity - closer to reference
characterReferences: [{ image: ref, fidelity: 0.9 }]

Image Input Formats

The SDK accepts multiple image formats:

// Buffer (from file)
const image = readFileSync('reference.png');

// Base64 string
const image = 'iVBORw0KGgoAAAANSUhEUgAA...';

// ArrayBuffer
const response = await fetch('https://example.com/image.png');
const image = await response.arrayBuffer();

Tips

1. Use clear reference images - Images with clear, unobstructed views of the character work best.

2. Match the prompt - Your prompt should describe the character in a way that's consistent with the reference.

3. Adjust fidelity - Start with the default (0.75) and adjust based on results.

4. Consider the type - Use 'character' if you want to change the art style, or 'character&style' to preserve it.

Limitations

• Currently only one character reference is supported per generation
• Only available for V4.5 models
• Very complex poses or angles may not transfer perfectly