Multi-Character Positioning

Position multiple characters in your image with individual prompts and positions.

WARNING

Multi-Character Positioning is only available for V4+ models.

Basic Usage

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

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

const images = await client.image.generate({
  prompt: 'two people standing in a park',
  model: 'nai-diffusion-4-5-full',
  characters: [
    {
      prompt: '1girl, red hair, blue eyes, wearing a dress',
      position: [0.25, 0.5],
      enabled: true,
    },
    {
      prompt: '1boy, black hair, green eyes, wearing a suit',
      position: [0.75, 0.5],
      enabled: true,
    },
  ],
});

Character Parameters

Parameter	Type	Default	Description
prompt	string	required	Character description
negativePrompt	string	''	What to avoid for this character
position	Position	[0.5, 0.5]	Position in image
enabled	boolean	true	Whether to include this character

Position System

Coordinate System

Positions are specified as [x, y] where:

• x: Horizontal position (0 = left, 1 = right)
• y: Vertical position (0 = top, 1 = bottom)

// Left side
position: [0.2, 0.5]

// Center
position: [0.5, 0.5]

// Right side
position: [0.8, 0.5]

// Top-left corner
position: [0.2, 0.2]

Position Presets

You can also use preset positions (A1-E5 grid):

import { positionPresetToCoords } from 'novelai-sdk-unofficial';

// Using preset
characters: [
  {
    prompt: '1girl',
    position: 'B2',
  },
]

// Convert preset to coordinates
const coords = positionPresetToCoords('B2'); // [0.3, 0.3]

Grid layout:

     A    B    C    D    E
1  [0.1, 0.1, 0.3, 0.5, 0.7, 0.9]
2  [0.1, 0.3, ...]
3  [0.1, 0.5, ...]
4  [0.1, 0.7, ...]
5  [0.1, 0.9, ...]

Examples

Two Characters Side by Side

const images = await client.image.generate({
  prompt: 'two friends talking',
  model: 'nai-diffusion-4-5-full',
  characters: [
    {
      prompt: '1girl, blonde hair, smiling',
      position: [0.3, 0.5],
    },
    {
      prompt: '1girl, brown hair, laughing',
      position: [0.7, 0.5],
    },
  ],
});

Three Characters

const images = await client.image.generate({
  prompt: 'group photo',
  model: 'nai-diffusion-4-5-full',
  characters: [
    {
      prompt: '1girl, red dress',
      position: [0.2, 0.5],
    },
    {
      prompt: '1boy, blue suit',
      position: [0.5, 0.5],
    },
    {
      prompt: '1girl, green dress',
      position: [0.8, 0.5],
    },
  ],
});

With Individual Negative Prompts

characters: [
  {
    prompt: '1girl, detailed face',
    negativePrompt: 'bad anatomy',
    position: [0.3, 0.5],
  },
  {
    prompt: '1boy, detailed face',
    negativePrompt: 'bad anatomy, blurry',
    position: [0.7, 0.5],
  },
]

Disabling a Character

characters: [
  {
    prompt: '1girl',
    position: [0.3, 0.5],
    enabled: true,
  },
  {
    prompt: '1boy',
    position: [0.7, 0.5],
    enabled: false, // This character won't appear
  },
]

Tips

1. Main prompt matters - The main prompt should describe the overall scene and composition.

2. Be specific - Each character's prompt should clearly describe their unique features.

3. Consider overlap - Characters positioned too close together may blend or overlap.

4. Test positions - Start with well-separated positions and adjust as needed.

Combining with Character Reference

You can use Character Reference with Multi-Character positioning (V4.5 only):

const images = await client.image.generate({
  prompt: 'two people in a cafe',
  model: 'nai-diffusion-4-5-full',
  characterReferences: [
    {
      image: referenceImage,
      fidelity: 0.75,
    },
  ],
  characters: [
    {
      prompt: '1girl, sitting',
      position: [0.3, 0.5],
    },
    {
      prompt: '1boy, standing',
      position: [0.7, 0.5],
    },
  ],
});