Build with NovelAI in
modern Python.
A type-safe, Pydantic v2-powered SDK for the NovelAI image generation API — V4 models, Precise Reference, ControlNet, SSE streaming.
Key Features
Built for production Python.
Type Safety
Python 3.10+ support, robust validation with Pydantic v2.
High-Level API
Intuitive, batteries-included interface for everyday use.
Modern Models
V4 model family, Precise Reference, ControlNet / Vibe Transfer.
Utilities
PIL/Pillow integration, SSE streaming, multi-character positioning.
Comparison with Alternatives
How novelai-sdk stacks up against the other unofficial Python clients.
| Feature | novelai-sdk | novelai-api | novelai-python |
|---|---|---|---|
| Type Safety (Pydantic v2) | ✅ | ❌ | ✅ |
| Async Support | ✅ | ✅ | ✅ |
| Image Generation | ✅ | ✅ | ✅ |
| Text Generation | 🚧 | ✅ | ✅ |
| Precise Reference | ✅ | ❌ | ❌ |
| Multi-Character Positioning | ✅ | ❌ | ✅ |
| ControlNet / Vibe Transfer | ✅ | ❌ | ✅ |
| SSE Streaming | ✅ | ❌ | ✅ |
| Python 3.10+ | ✅ | ❌ | ❌ |
| Active Maintenance | ✅ | ✅ | ⚠️ |
✅ Supported · ❌ Not supported · 🚧 Planned · ⚠️ Limited maintenance
Data Model Architecture
The library is designed with two distinct layers of data models.
User Model (Recommended)
User-friendly models with sensible defaults and automatic validation.
API Model
Direct 1:1 mapping to NovelAI's API endpoints, primarily used internally.
One client. One call. One image.
Initialize, configure, generate — all type-checked.
from novelai import NovelAI
from novelai.types import GenerateImageParams
client = NovelAI() # picks up NOVELAI_API_KEY from env
params = GenerateImageParams(
prompt="1girl, cat ears, masterpiece, best quality",
model="nai-diffusion-4-5-full",
size="portrait",
steps=28,
scale=5.0,
)
images = client.image.generate(params)
images[0].save("output.png")