novelai-sdk 0.3.0

A Python SDK library for the NovelAI API with validation powered by Pydantic

NovelAI Python SDK

English | 日本語

A modern, type-safe Python SDK for NovelAI's image generation API. Features robust validation with Pydantic v2 and complete type hints.

Features

• Python 3.10+ with full type hints and Pydantic v2 validation
• High-level convenience API with automatic validation
• Built-in PIL/Pillow support for easy image operations
• SSE streaming for real-time progress monitoring
• Character references, ControlNet, and multi-character positioning

Quick Start

Installation

# Using pip
pip install novelai-sdk

# Using uv (recommended)
uv add novelai-sdk

Basic Usage

from novelai import NovelAI
from novelai.types import GenerateImageParams

# Initialize client (API key from NOVELAI_API_KEY environment variable)
client = NovelAI()

# Generate an image
params = GenerateImageParams(
    prompt="1girl, cat ears, masterpiece, best quality",
    model="nai-diffusion-4-5-full",
    size="portrait",  # or (832, 1216)
    steps=23,
    scale=5.0,
)

images = client.image.generate(params)
images[0].save("output.png")

Documentation

Authentication

Provide your NovelAI API key via environment variable or direct initialization:

# Using .env file (recommended)
from dotenv import load_dotenv
load_dotenv()
client = NovelAI()

# Environment variable
import os
os.environ["NOVELAI_API_KEY"] = "your_api_key_here"
client = NovelAI()

# Direct initialization
client = NovelAI(api_key="your_api_key_here")

API Architecture

The library provides a high-level API with sensible defaults and automatic validation. A low-level API exists internally for direct REST endpoint access, but is not intended for general use.

High-Level API

from novelai import NovelAI
from novelai.types import GenerateImageParams

client = NovelAI()
params = GenerateImageParams(
    prompt="a beautiful landscape",
    model="nai-diffusion-4-5-full",
    size="landscape",
    quality=True,
)
images = client.image.generate(params)

Advanced Features

Character Reference

Maintain consistent character appearances with reference images:

from novelai.types import CharacterReference

character_references = [
    CharacterReference(
        image="reference.png",
        type="character",
        fidelity=0.75,
    )
]

params = GenerateImageParams(
    prompt="1girl, standing",
    model="nai-diffusion-4-5-full",
    character_references=character_references,
)

Multi-Character Positioning

Position multiple characters individually with separate prompts:

from novelai.types import Character

characters = [
    Character(
        prompt="1girl, red hair, blue eyes",
        enabled=True,
        position=(0.2, 0.5),
    ),
    Character(
        prompt="1boy, black hair, green eyes",
        enabled=True,
        position=(0.8, 0.5),
    ),
]

params = GenerateImageParams(
    prompt="two people standing",
    model="nai-diffusion-4-5-full",
    characters=characters,
)

ControlNet (Vibe Transfer)

Control composition and pose with reference images:

from novelai.types import ControlNetModel

params = GenerateImageParams(
    prompt="1girl, standing",
    model="nai-diffusion-4-5-full",
    controlnet_model=ControlNetModel(
        image="pose_reference.png",
        strength=0.6,
    ),
)

Streaming Generation

Monitor generation progress in real-time:

from novelai.types import GenerateImageStreamParams
from base64 import b64decode

params = GenerateImageStreamParams(
    prompt="1girl, standing",
    model="nai-diffusion-4-5-full",
    stream="sse",
)

for chunk in client.image.generate_stream(params):
    image_data = b64decode(chunk.image)
    print(f"Received {len(image_data)} bytes")

Image-to-Image

Transform existing images with text prompts:

params = GenerateImageParams(
    prompt="cyberpunk style",
    model="nai-diffusion-4-5-full",
    image="input.png",
    strength=0.5,  # 0.0-1.0
)

Batch Generation

Generate multiple variations efficiently:

params = GenerateImageParams(
    prompt="1girl, various poses",
    model="nai-diffusion-4-5-full",
    n_samples=4,
)

images = client.image.generate(params)
for i, img in enumerate(images):
    img.save(f"output_{i}.png")

Examples

The examples/ directory contains practical demonstrations:

Basic Usage:

• 01_basic_v4.py - Getting started with V4 model
• 08_img2img.py - Image-to-image transformation

Advanced Features:

• 02_character_reference.py - Character reference
• 03_character_prompts.py - Multi-character positioning
• 04_advanced_reference.py - Combined reference techniques
• 05_controlnet.py - ControlNet usage

Generation Techniques:

• 06_batch_generation.py - Batch generation
• 07_streaming_generation.py - Streaming progress

Run any example:

python examples/01_basic_v4.py

Loadmap

• Async support
• Vibe transfer file support (.naiv4vibe,.naiv4vibebundle)
• Anlas consuption calculator
• Image metadata extraction
• Text generation API support

Development

Setup

git clone https://github.com/caru-ini/novelai-sdk.git
cd novelai-sdk
uv sync

Code Quality

# Format code
uv run poe fmt

# Lint code
uv run poe lint

# Type checking
uv run poe check

# Install poe globally for easier access
uv tool install poe

# Run all checks before committing
uv run poe pre-commit

Testing

Tests will be added in future releases.

Requirements

• Python 3.13+
• httpx (HTTP client)
• Pillow (image processing)
• Pydantic v2 (validation and type safety)
• python-dotenv (environment variables)

Contributing

Contributions are welcome. For major changes, please open an issue first.

Commit Guidelines

{feat|fix|docs|style|refactor|test|chore}: Short description

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Run code quality checks (uv run poe pre-commit)
4. Commit your changes (git commit -m 'Add some AmazingFeature')
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

License

MIT License. See LICENSE file for details.

Links

• NovelAI Official Website
• NovelAI Documentation
• Issue

Disclaimer

This is an unofficial client library. Not affiliated with NovelAI. Requires an active NovelAI subscription.

Acknowledgments

Thanks to the NovelAI team and all contributors.