novelai_image_mcp.nai —— NovelAI HTTP 客户端

nai/ 子包是 NovelAI HTTP 客户端。它与 MCP 无关 —— 可以在任何异步 Python 代码中独立使用,不依赖 MCP 服务器。

子模块

novelai_image_mcp.nai.client

高层异步客户端。在共享的 httpx.AsyncClient 之上封装了线格式编码器 (payload.build_generation_payload)与响应解码器 (response.parse_messagepack_images)。

Complete NovelAI HTTP client built on a shared httpx async session.

A long-lived httpx.AsyncClient is owned by the instance (or supplied by the MCP lifespan) and used for all NovelAI API traffic. Covers generation, Director, utility, and account business logic.

exception novelai_image_mcp.nai.client.MissingNovelAITokenError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIAuthenticationError

No usable NovelAI credential is configured.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

class novelai_image_mcp.nai.client.NovelAIClient(credentials, *, http_client=None, image_base_url='https://image.novelai.net', account_base_url='https://image.novelai.net', legacy_image_base_url='https://api.novelai.net', timeout=120.0, vibe_cache_entries=64)[源代码]

基类:object

Project-owned client for generation, tools, utilities, and account APIs.

参数:
  • credentials (NovelAICredentials)

  • http_client (httpx.AsyncClient | None)

  • image_base_url (str)

  • account_base_url (str)

  • legacy_image_base_url (str)

  • timeout (float)

  • vibe_cache_entries (int)

async aclose()[源代码]

Close the underlying HTTP session when owned by this client.

返回类型:

None

async get_access_token()[源代码]
返回类型:

str

async encode_vibe(reference, *, information_extracted, model)[源代码]
参数:
返回类型:

str

async generate(request)[源代码]
参数:

request (GenerationRequest)

返回类型:

tuple[NovelAIImage, ...]

async stream_generation(request)[源代码]

Yield V4 / V4.5 / V5 events as the active driver produces chunks.

参数:

request (GenerationRequest)

返回类型:

AsyncIterator[GenerationEvent]

async director(tool, image, *, prompt='', defry=0, emotion=None, emotion_level=EmotionLevel.NORMAL)[源代码]
参数:
返回类型:

NovelAIImage

async upscale(image, *, factor=4, model=None)[源代码]

Upscale an image 4x with NovelAI's standalone upscaler.

The endpoint lives on image.novelai.net and takes {image, model, declared_blur_sigma}. It is 4x only — the API exposes no scaling factor — and only the V5 line supports standalone upscaling, so model defaults to the V5 full model (see NovelAISettings.upscale_model).

Verified live on 2026-10-10: V3 / V4 / V4.5 (including their inpainting and curated variants) are rejected with "model ... doesn't support standalone upscaling".

参数:
返回类型:

NovelAIImage

async annotate(image, model)[源代码]
参数:
返回类型:

NovelAIImage

async suggest_tags(prompt, *, model=Model.V4_5, language='en')[源代码]
参数:
返回类型:

tuple[dict[str, Any], ...]

async get_subscription()[源代码]
返回类型:

dict[str, Any]

async get_user_data()[源代码]
返回类型:

dict[str, Any]

exception novelai_image_mcp.nai.client.NovelAIError(message, *, code=None, explanation=None)

基类:Exception

Base class for NovelAI failures.

code is the NovelAI error code when known (None for transport, timeout, or local validation failures that carry no server code); explanation is NovelAI's official explanation for documented codes.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.client.NovelAIProviderError(message, *, code=None, explanation=None)

基类:NovelAIError

NovelAI rejected or failed the request.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.client.NovelAIResponseError(message, *, code=None, explanation=None)

基类:NovelAIError

NovelAI returned malformed or unsupported data.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.client.NovelAITimeoutError(message, *, code=None, explanation=None)

基类:NovelAIError

A request exceeded its timeout.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.client.NovelAITransportError(message, *, code=None, explanation=None)

基类:NovelAIError

The request could not reach NovelAI.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

novelai_image_mcp.nai.client.extract_final_image(content)[源代码]
参数:

content (bytes)

返回类型:

bytes

async novelai_image_mcp.nai.client.generate_image_from_plan(plan, *, client, n_samples=1, quality=True, uc_preset=0, noise_schedule='karras', cfg_rescale=0.0, dynamic_thresholding=False, auto_smea=False, prefer_brownian=True)[源代码]

Generate a single image from a high-level plan (used by the sync CLI).

The caller supplies the configured client plus the generation defaults (read from settings, not from a global config).

参数:
返回类型:

bytes

novelai_image_mcp.nai.constants

NovelAI API 接口面的枚举:Action、Model、Sampler、 DirectorTool、Emotion、EmotionLevel、ControlNetModel、Endpoint、 NoiseSchedule。以及谓词函数 is_v4_model、is_v5_model、 supports_vibe 与 is_inpaint_model。

NovelAI protocol constants and model capability helpers.

class novelai_image_mcp.nai.constants.IntEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

基类:int, ReprEnum

Enum where members are also (and must be) ints

class novelai_image_mcp.nai.constants.StrEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

基类:str, ReprEnum

Enum where members are also (and must be) strings

__new_member__(*values)

values must already be of type str

class novelai_image_mcp.nai.constants.Endpoint(*values)[源代码]

基类:StrEnum

NovelAI API path constants.

Most paths are rooted at https://image.novelai.net (the consolidated third-party host), UPSCALE (/ai/upscale, V5 models only) included. ANNOTATE is the one exception: /ai/annotate-image was never migrated and remains on the Primary API at https://api.novelai.net. The Primary API's docs (https://api.novelai.net/docs/) state that third-party users may use its /ai/ routes. See NovelAIClient.legacy_image_base_url.

The /ai/generate-image family is split by model generation:

  • IMAGE (/ai/generate-image) — used by V3 / Furry legacy models. Returns a ZIP archive (application/zip) with HTTP 201.

  • IMAGE_STREAM (/ai/generate-image-stream) — used by V4 / V4.5 / V5 new models. Returns a MessagePack stream (stream: "msgpack") with HTTP 200. The selection is driven by is_v4_model in client.py.

LOGIN = '/user/login'
USER_DATA = '/user/data'
SUBSCRIPTION = '/user/subscription'
IMAGE = '/ai/generate-image'
IMAGE_STREAM = '/ai/generate-image-stream'
DIRECTOR = '/ai/augment-image'
ENCODE_VIBE = '/ai/encode-vibe'
UPSCALE = '/ai/upscale'
ANNOTATE = '/ai/annotate-image'
SUGGEST_TAGS = '/ai/generate-image/suggest-tags'
class novelai_image_mcp.nai.constants.Model(*values)[源代码]

基类:StrEnum

V3 = 'nai-diffusion-3'
V3_INPAINT = 'nai-diffusion-3-inpainting'
FURRY = 'nai-diffusion-furry-3'
FURRY_INPAINT = 'nai-diffusion-furry-3-inpainting'
V4 = 'nai-diffusion-4-full'
V4_INPAINT = 'nai-diffusion-4-full-inpainting'
V4_CURATED = 'nai-diffusion-4-curated-preview'
V4_CURATED_INPAINT = 'nai-diffusion-4-curated-inpainting'
V4_5 = 'nai-diffusion-4-5-full'
V4_5_INPAINT = 'nai-diffusion-4-5-full-inpainting'
V4_5_CURATED = 'nai-diffusion-4-5-curated'
V4_5_CURATED_INPAINT = 'nai-diffusion-4-5-curated-inpainting'
V5 = 'nai-diffusion-5-full'
V5_CURATED = 'nai-diffusion-5-curated'
V5_INPAINT = 'nai-diffusion-5-full-inpainting'
class novelai_image_mcp.nai.constants.Action(*values)[源代码]

基类:StrEnum

GENERATE = 'generate'
IMG2IMG = 'img2img'
INPAINT = 'infill'
class novelai_image_mcp.nai.constants.Sampler(*values)[源代码]

基类:StrEnum

EULER = 'k_euler'
EULER_ANCESTRAL = 'k_euler_ancestral'
DPM_2S_ANCESTRAL = 'k_dpmpp_2s_ancestral'
DPM_2M = 'k_dpmpp_2m'
DPM_2M_SDE = 'k_dpmpp_2m_sde'
DPM_SDE = 'k_dpmpp_sde'
DDIM = 'ddim_v3'
class novelai_image_mcp.nai.constants.NoiseSchedule(*values)[源代码]

基类:StrEnum

NATIVE = 'native'
KARRAS = 'karras'
EXPONENTIAL = 'exponential'
POLYEXPONENTIAL = 'polyexponential'
class novelai_image_mcp.nai.constants.ControlNetModel(*values)[源代码]

基类:StrEnum

PALETTE_SWAP = 'hed'
FORM_LOCK = 'midas'
SCRIBBLER = 'fake_scribble'
BUILDING_CONTROL = 'mlsd'
LANDSCAPER = 'uniformer'
class novelai_image_mcp.nai.constants.DirectorTool(*values)[源代码]

基类:StrEnum

LINE_ART = 'lineart'
SKETCH = 'sketch'
BACKGROUND_REMOVAL = 'bg-removal'
DECLUTTER = 'declutter'
COLORIZE = 'colorize'
EMOTION = 'emotion'
class novelai_image_mcp.nai.constants.Emotion(*values)[源代码]

基类:StrEnum

NEUTRAL = 'neutral'
HAPPY = 'happy'
SAD = 'sad'
ANGRY = 'angry'
SCARED = 'scared'
SURPRISED = 'surprised'
TIRED = 'tired'
EXCITED = 'excited'
NERVOUS = 'nervous'
THINKING = 'thinking'
CONFUSED = 'confused'
SHY = 'shy'
DISGUSTED = 'disgusted'
SMUG = 'smug'
BORED = 'bored'
LAUGHING = 'laughing'
IRRITATED = 'irritated'
AROUSED = 'aroused'
EMBARRASSED = 'embarrassed'
WORRIED = 'worried'
LOVE = 'love'
DETERMINED = 'determined'
HURT = 'hurt'
PLAYFUL = 'playful'
class novelai_image_mcp.nai.constants.EmotionLevel(*values)[源代码]

基类:IntEnum

NORMAL = 0
SLIGHTLY_WEAK = 1
WEAK = 2
EVEN_WEAKER = 3
VERY_WEAK = 4
WEAKEST = 5
novelai_image_mcp.nai.constants.is_v4_model(model)[源代码]

True for structured-prompt (V4+) models: V4 / V4.5 / V5 families.

These use the /ai/generate-image-stream endpoint (MessagePack) and the v4_prompt / v4_negative_prompt caption payload shape. The name is retained for backward compatibility (public nai API).

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.constants.is_v5_model(model)[源代码]

True for NovelAI Diffusion V5 models (Full / Curated / Inpainting).

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.constants.supports_vibe(model)[源代码]

True when vibe transfer (reference images) works for this model.

Vibe transfer is available on V4 / V4.5 only — V3 / Furry and V5 (feature not yet released for V5 per the official announcement) return False.

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.constants.is_inpaint_model(model)[源代码]
参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.constants.UPSCALE_MODELS = frozenset({Model.V5_CURATED, Model.V5})

Models the standalone upscaler accepts. Live-verified 2026-10-10 against POST https://image.novelai.net/ai/upscale: the V5 line returns 200 while every V3 / V4 / V4.5 variant (inpainting and curated included) is rejected with "model ... doesn't support standalone upscaling".

novelai_image_mcp.nai.constants.supports_upscale(model)[源代码]

True when the standalone /ai/upscale endpoint accepts this model.

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.constants.params_version_for(model)[源代码]

Return the NovelAI params_version for a model.

V5 clients ship both 3 (Marinara-Engine) and 4 (Auto-NovelAI, SDlab) and the API tolerates either; this project sends 4 for V5 (the value used by the most recent third-party implementations) and 3 for older generations, pending live verification.

参数:

model (Model)

返回类型:

int

novelai_image_mcp.nai.models

线格式的 Pydantic 模型:GenerationRequest、 CharacterPrompt、NovelAIGenerationPlan。

Pure value objects shared by the NovelAI generation pipeline.

novelai_image_mcp.nai.models.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

class novelai_image_mcp.nai.models.Action(*values)

基类:StrEnum

GENERATE = 'generate'
IMG2IMG = 'img2img'
INPAINT = 'infill'
class novelai_image_mcp.nai.models.Model(*values)

基类:StrEnum

V3 = 'nai-diffusion-3'
V3_INPAINT = 'nai-diffusion-3-inpainting'
FURRY = 'nai-diffusion-furry-3'
FURRY_INPAINT = 'nai-diffusion-furry-3-inpainting'
V4 = 'nai-diffusion-4-full'
V4_INPAINT = 'nai-diffusion-4-full-inpainting'
V4_CURATED = 'nai-diffusion-4-curated-preview'
V4_CURATED_INPAINT = 'nai-diffusion-4-curated-inpainting'
V4_5 = 'nai-diffusion-4-5-full'
V4_5_INPAINT = 'nai-diffusion-4-5-full-inpainting'
V4_5_CURATED = 'nai-diffusion-4-5-curated'
V4_5_CURATED_INPAINT = 'nai-diffusion-4-5-curated-inpainting'
V5 = 'nai-diffusion-5-full'
V5_CURATED = 'nai-diffusion-5-curated'
V5_INPAINT = 'nai-diffusion-5-full-inpainting'
class novelai_image_mcp.nai.models.NoiseSchedule(*values)

基类:StrEnum

NATIVE = 'native'
KARRAS = 'karras'
EXPONENTIAL = 'exponential'
POLYEXPONENTIAL = 'polyexponential'
class novelai_image_mcp.nai.models.Sampler(*values)

基类:StrEnum

EULER = 'k_euler'
EULER_ANCESTRAL = 'k_euler_ancestral'
DPM_2S_ANCESTRAL = 'k_dpmpp_2s_ancestral'
DPM_2M = 'k_dpmpp_2m'
DPM_2M_SDE = 'k_dpmpp_2m_sde'
DPM_SDE = 'k_dpmpp_sde'
DDIM = 'ddim_v3'
novelai_image_mcp.nai.models.is_inpaint_model(model)
参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.models.is_v4_model(model)

True for structured-prompt (V4+) models: V4 / V4.5 / V5 families.

These use the /ai/generate-image-stream endpoint (MessagePack) and the v4_prompt / v4_negative_prompt caption payload shape. The name is retained for backward compatibility (public nai API).

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.models.normalize_tags(values)[源代码]

Trim tags and remove case-insensitive duplicates while preserving order.

参数:

values (tuple[str, ...])

返回类型:

tuple[str, ...]

novelai_image_mcp.nai.models.normalize_negative_prompt(value)[源代码]

Split comma/newline negative prompt text into normalized tags.

参数:

value (str | None)

返回类型:

tuple[str, ...]

class novelai_image_mcp.nai.models.PositionCoord(x: 'float', y: 'float')[源代码]

基类:object

参数:
x: float
y: float
class novelai_image_mcp.nai.models.CharacterIntent(description: 'str', tags: 'tuple[str, ...]', negative_tags: 'tuple[str, ...]', center: 'PositionCoord')[源代码]

基类:object

参数:
description: str
tags: tuple[str, ...]
negative_tags: tuple[str, ...]
center: PositionCoord
class novelai_image_mcp.nai.models.GenerationHints(width: 'int | None' = None, height: 'int | None' = None, steps: 'int | None' = None, scale: 'float | None' = None, sampler: 'str | None' = None, seed: 'int | None' = None, negative_tags: 'tuple[str, ...]' = ())[源代码]

基类:object

参数:
  • width (int | None)

  • height (int | None)

  • steps (int | None)

  • scale (float | None)

  • sampler (str | None)

  • seed (int | None)

  • negative_tags (tuple[str, ...])

width: int | None
height: int | None
steps: int | None
scale: float | None
sampler: str | None
seed: int | None
negative_tags: tuple[str, ...]
class novelai_image_mcp.nai.models.PromptIntent(source_language: 'str', english_description: 'str', base_tags: 'tuple[str, ...]', generation: 'GenerationHints', characters: 'tuple[CharacterIntent, ...]', search_required: 'bool', search_query: 'str | None', search_reason: 'str | None')[源代码]

基类:object

参数:
source_language: str
english_description: str
base_tags: tuple[str, ...]
generation: GenerationHints
characters: tuple[CharacterIntent, ...]
search_required: bool
search_query: str | None
search_reason: str | None
class novelai_image_mcp.nai.models.VisualResearch(facts: 'tuple[str, ...]', sources: 'tuple[str, ...]')[源代码]

基类:object

参数:
facts: tuple[str, ...]
sources: tuple[str, ...]
class novelai_image_mcp.nai.models.TipoRequest(description: 'str', tags: 'tuple[str, ...]', visual_facts: 'tuple[str, ...]', seed: 'int')[源代码]

基类:object

参数:
description: str
tags: tuple[str, ...]
visual_facts: tuple[str, ...]
seed: int
class novelai_image_mcp.nai.models.TipoPrompt(natural_language: 'str', tags: 'tuple[str, ...]')[源代码]

基类:object

参数:
natural_language: str
tags: tuple[str, ...]
class novelai_image_mcp.nai.models.GenerationOverrides(width: 'int | None' = None, height: 'int | None' = None, steps: 'int | None' = None, scale: 'float | None' = None, sampler: 'str | None' = None, seed: 'int | None' = None, negative_prompt: 'str | None' = None)[源代码]

基类:object

参数:
  • width (int | None)

  • height (int | None)

  • steps (int | None)

  • scale (float | None)

  • sampler (str | None)

  • seed (int | None)

  • negative_prompt (str | None)

width: int | None
height: int | None
steps: int | None
scale: float | None
sampler: str | None
seed: int | None
negative_prompt: str | None
class novelai_image_mcp.nai.models.NovelAIGenerationPlan(prompt: 'str', negative_prompt: 'str', width: 'int', height: 'int', steps: 'int', scale: 'float', sampler: 'str', seed: 'int', base_caption: 'str', char_captions: 'tuple[dict[str, object], ...]', character_prompts: 'tuple[dict[str, object], ...]', use_coords: 'bool')[源代码]

基类:object

参数:
prompt: str
negative_prompt: str
width: int
height: int
steps: int
scale: float
sampler: str
seed: int
base_caption: str
char_captions: tuple[dict[str, object], ...]
character_prompts: tuple[dict[str, object], ...]
use_coords: bool
class novelai_image_mcp.nai.models.CharacterPrompt(prompt: 'str', negative_prompt: 'str' = '', x: 'float' = 0.5, y: 'float' = 0.5, enabled: 'bool' = True)[源代码]

基类:object

参数:
prompt: str
negative_prompt: str
x: float
y: float
enabled: bool
class novelai_image_mcp.nai.models.GenerationRequest(prompt, base_caption=None, model=Model.V4_5, action=Action.GENERATE, negative_prompt='', width=832, height=1216, n_samples=1, steps=28, scale=5.0, sampler=Sampler.EULER_ANCESTRAL, seed=0, extra_noise_seed=None, noise_schedule=NoiseSchedule.KARRAS, quality=True, uc_preset=0, dynamic_thresholding=False, cfg_rescale=0.0, smea=None, smea_dynamic=None, auto_smea=False, image=None, mask=None, strength=None, noise=None, add_original_image=True, controlnet_strength=1.0, controlnet_condition=None, controlnet_model=None, references=(), reference_information=(), reference_strengths=(), character_prompts=(), use_coords=False, use_order=True, legacy_uc=False, normalize_reference_strengths=True, deliberate_euler_ancestral_bug=False, prefer_brownian=True, skip_cfg_above_sigma=None, legacy=False, legacy_v3_extend=False, inpaint_img2img_strength=None, straight_alpha=False, estimate_only=False)[源代码]

基类:object

Complete NovelAI generation request independent of the chat planner.

参数:
prompt: str
base_caption: str | None
model: Model
action: Action
negative_prompt: str
width: int
height: int
n_samples: int
steps: int
scale: float
sampler: Sampler | str
seed: int
extra_noise_seed: int | None
noise_schedule: NoiseSchedule | str
quality: bool
uc_preset: int
dynamic_thresholding: bool
cfg_rescale: float
smea: bool | None
smea_dynamic: bool | None
auto_smea: bool
image: str | None
mask: str | None
strength: float | None
noise: float | None
add_original_image: bool
controlnet_strength: float
controlnet_condition: str | None
controlnet_model: str | None
references: tuple[str, ...]
reference_information: tuple[float, ...]
reference_strengths: tuple[float, ...]
character_prompts: tuple[CharacterPrompt, ...]
use_coords: bool
use_order: bool
legacy_uc: bool
normalize_reference_strengths: bool
deliberate_euler_ancestral_bug: bool
prefer_brownian: bool
skip_cfg_above_sigma: int | None
legacy: bool
legacy_v3_extend: bool
inpaint_img2img_strength: int | None
straight_alpha: bool
estimate_only: bool
property effective_prompt: str[源代码]
property effective_base_caption: str[源代码]
property effective_negative_prompt: str[源代码]
property max_samples: int[源代码]
estimate_anlas_cost(*, opus=False)[源代码]

Estimate provider Anlas cost using the public web-client formula.

Note: on V5, Opus free generations (normal resolution, <=28 steps) are subject to NovelAI's refillable "battery" usage limit; once exhausted the API silently bills Anlas instead of erroring, so the estimate here covers the paid cost regardless of quota state.

参数:

opus (bool)

返回类型:

int

novelai_image_mcp.nai.auth

Argon2id access-key 派生 + 每请求的追踪头。

NovelAI credential validation and access-key derivation.

novelai_image_mcp.nai.auth.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

class novelai_image_mcp.nai.auth.datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])

基类:date

The year, month and day arguments are required. tzinfo may be None, or an instance of a tzinfo subclass. The remaining arguments may be ints.

astimezone()

tz -> convert to local time in new timezone tz

classmethod combine()

date, time -> datetime with same date and time fields

ctime()

Return ctime() style string.

date()

Return date object with same year, month and day.

dst()

Return self.tzinfo.dst(self).

fold
classmethod fromisoformat(object, /)

string -> datetime from a string in most ISO 8601 formats

classmethod fromtimestamp()

timestamp[, tz] -> tz's local time from POSIX timestamp.

hour
isoformat()

[sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM]. sep is used to separate the year from the time, and defaults to 'T'. The optional argument timespec specifies the number of additional terms of the time to include. Valid options are 'auto', 'hours', 'minutes', 'seconds', 'milliseconds' and 'microseconds'.

max = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999)
microsecond
min = datetime.datetime(1, 1, 1, 0, 0)
minute
classmethod now(tz=None)

Returns new datetime object representing current time local to tz.

tz

Timezone object.

If no tz is specified, uses local timezone.

replace()

Return datetime with new specified fields.

resolution = datetime.timedelta(microseconds=1)
second
classmethod strptime()

string, format -> new datetime parsed from a string (like time.strptime()).

time()

Return time object with same time but with tzinfo=None.

timestamp()

Return POSIX timestamp as float.

timetuple()

Return time tuple, compatible with time.localtime().

timetz()

Return time object with same time and tzinfo.

tzinfo
tzname()

Return self.tzinfo.tzname(self).

classmethod utcfromtimestamp()

Construct a naive UTC datetime from a POSIX timestamp.

classmethod utcnow()

Return a new datetime representing UTC day and time.

utcoffset()

Return self.tzinfo.utcoffset(self).

utctimetuple()

Return UTC time tuple, compatible with time.localtime().

class novelai_image_mcp.nai.auth.blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True, string=None)

基类:object

Return a new BLAKE2b hash object.

MAX_DIGEST_SIZE = 64
MAX_KEY_SIZE = 64
PERSON_SIZE = 16
SALT_SIZE = 16
block_size
copy()

Return a copy of the hash object.

digest()

Return the digest value as a bytes object.

digest_size
hexdigest()

Return the digest value as a string of hexadecimal digits.

name
update(data, /)

Update this hash object's state with the provided bytes-like object.

class novelai_image_mcp.nai.auth.NovelAICredentials(token: 'str | None' = None, username: 'str | None' = None, password: 'str | None' = None)[源代码]

基类:object

参数:
  • token (str | None)

  • username (str | None)

  • password (str | None)

token: str | None
username: str | None
password: str | None
novelai_image_mcp.nai.auth.derive_access_key(credentials)[源代码]

Derive the 64-character NovelAI login key from username/password.

参数:

credentials (NovelAICredentials)

返回类型:

str

novelai_image_mcp.nai.auth.request_tracking_headers()[源代码]

Build fresh tracking headers expected by NovelAI's browser-facing APIs.

返回类型:

dict[str, str]

novelai_image_mcp.nai.payload

build_generation_payload —— 线格式编码器(兼容 MessagePack)。

NovelAI V4+ / V5 wire payload mapping.

class novelai_image_mcp.nai.payload.Model(*values)

基类:StrEnum

V3 = 'nai-diffusion-3'
V3_INPAINT = 'nai-diffusion-3-inpainting'
FURRY = 'nai-diffusion-furry-3'
FURRY_INPAINT = 'nai-diffusion-furry-3-inpainting'
V4 = 'nai-diffusion-4-full'
V4_INPAINT = 'nai-diffusion-4-full-inpainting'
V4_CURATED = 'nai-diffusion-4-curated-preview'
V4_CURATED_INPAINT = 'nai-diffusion-4-curated-inpainting'
V4_5 = 'nai-diffusion-4-5-full'
V4_5_INPAINT = 'nai-diffusion-4-5-full-inpainting'
V4_5_CURATED = 'nai-diffusion-4-5-curated'
V4_5_CURATED_INPAINT = 'nai-diffusion-4-5-curated-inpainting'
V5 = 'nai-diffusion-5-full'
V5_CURATED = 'nai-diffusion-5-curated'
V5_INPAINT = 'nai-diffusion-5-full-inpainting'
novelai_image_mcp.nai.payload.is_v4_model(model)

True for structured-prompt (V4+) models: V4 / V4.5 / V5 families.

These use the /ai/generate-image-stream endpoint (MessagePack) and the v4_prompt / v4_negative_prompt caption payload shape. The name is retained for backward compatibility (public nai API).

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.payload.is_v5_model(model)

True for NovelAI Diffusion V5 models (Full / Curated / Inpainting).

参数:

model (Model)

返回类型:

bool

novelai_image_mcp.nai.payload.params_version_for(model)

Return the NovelAI params_version for a model.

V5 clients ship both 3 (Marinara-Engine) and 4 (Auto-NovelAI, SDlab) and the API tolerates either; this project sends 4 for V5 (the value used by the most recent third-party implementations) and 3 for older generations, pending live verification.

参数:

model (Model)

返回类型:

int

class novelai_image_mcp.nai.payload.GenerationRequest(prompt, base_caption=None, model=Model.V4_5, action=Action.GENERATE, negative_prompt='', width=832, height=1216, n_samples=1, steps=28, scale=5.0, sampler=Sampler.EULER_ANCESTRAL, seed=0, extra_noise_seed=None, noise_schedule=NoiseSchedule.KARRAS, quality=True, uc_preset=0, dynamic_thresholding=False, cfg_rescale=0.0, smea=None, smea_dynamic=None, auto_smea=False, image=None, mask=None, strength=None, noise=None, add_original_image=True, controlnet_strength=1.0, controlnet_condition=None, controlnet_model=None, references=(), reference_information=(), reference_strengths=(), character_prompts=(), use_coords=False, use_order=True, legacy_uc=False, normalize_reference_strengths=True, deliberate_euler_ancestral_bug=False, prefer_brownian=True, skip_cfg_above_sigma=None, legacy=False, legacy_v3_extend=False, inpaint_img2img_strength=None, straight_alpha=False, estimate_only=False)

基类:object

Complete NovelAI generation request independent of the chat planner.

参数:
prompt: str
base_caption: str | None
model: Model
action: Action
negative_prompt: str
width: int
height: int
n_samples: int
steps: int
scale: float
sampler: Sampler | str
seed: int
extra_noise_seed: int | None
noise_schedule: NoiseSchedule | str
quality: bool
uc_preset: int
dynamic_thresholding: bool
cfg_rescale: float
smea: bool | None
smea_dynamic: bool | None
auto_smea: bool
image: str | None
mask: str | None
strength: float | None
noise: float | None
add_original_image: bool
controlnet_strength: float
controlnet_condition: str | None
controlnet_model: str | None
references: tuple[str, ...]
reference_information: tuple[float, ...]
reference_strengths: tuple[float, ...]
character_prompts: tuple[CharacterPrompt, ...]
use_coords: bool
use_order: bool
legacy_uc: bool
normalize_reference_strengths: bool
deliberate_euler_ancestral_bug: bool
prefer_brownian: bool
skip_cfg_above_sigma: int | None
legacy: bool
legacy_v3_extend: bool
inpaint_img2img_strength: int | None
straight_alpha: bool
estimate_only: bool
property effective_prompt: str
property effective_base_caption: str
property effective_negative_prompt: str
property max_samples: int
estimate_anlas_cost(*, opus=False)

Estimate provider Anlas cost using the public web-client formula.

Note: on V5, Opus free generations (normal resolution, <=28 steps) are subject to NovelAI's refillable "battery" usage limit; once exhausted the API silently bills Anlas instead of erroring, so the estimate here covers the paid cost regardless of quota state.

参数:

opus (bool)

返回类型:

int

class novelai_image_mcp.nai.payload.NovelAIGenerationPlan(prompt: 'str', negative_prompt: 'str', width: 'int', height: 'int', steps: 'int', scale: 'float', sampler: 'str', seed: 'int', base_caption: 'str', char_captions: 'tuple[dict[str, object], ...]', character_prompts: 'tuple[dict[str, object], ...]', use_coords: 'bool')

基类:object

参数:
prompt: str
negative_prompt: str
width: int
height: int
steps: int
scale: float
sampler: str
seed: int
base_caption: str
char_captions: tuple[dict[str, object], ...]
character_prompts: tuple[dict[str, object], ...]
use_coords: bool
novelai_image_mcp.nai.payload.build_payload(plan, *, model)[源代码]

Map an already-resolved plan to NovelAI's V4.5/V5 request shape.

参数:
返回类型:

dict[str, Any]

novelai_image_mcp.nai.payload.build_generation_payload(request)[源代码]

Serialize every supported generation and conditioning option.

参数:

request (GenerationRequest)

返回类型:

dict[str, Any]

novelai_image_mcp.nai.response

响应解析:NovelAIImage、parse_messagepack_images、 parse_zip_images、check_status、GenerationEvent。

NovelAI HTTP, ZIP, and MessagePack response parsing.

novelai_image_mcp.nai.response.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

class novelai_image_mcp.nai.response.Any(*args, **kwargs)

基类:object

Special type indicating an unconstrained type.

  • Any is assignable to every type.

  • Any assumed to have all methods and attributes.

  • All values are assignable to Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any cannot be used with instance checks.

novelai_image_mcp.nai.response.cast(typ, val)

Cast a value to a type.

This returns the value unchanged. To the type checker this signals that the return value has the designated type, but at runtime we intentionally don't check anything (we want this to be as fast as possible).

novelai_image_mcp.nai.response.explain(code)

Return NovelAI's official explanation for a documented error code.

Undocumented codes (including API-supplied MessagePack stream codes) return None — the API's own message is then the best explanation.

参数:

code (int | str | None)

返回类型:

str | None

novelai_image_mcp.nai.response.parse_error_body(content)

Extract (code, message) from a NovelAI error body.

NovelAI returns JSON in several shapes — {"statusCode", "message"}, {"code", "message"}, {"error": ...}, or a bare {"message"} — or, on some legacy paths, raw text. Falls back to the decoded text when neither a code nor a message field is present.

参数:

content (bytes)

返回类型:

ErrorInfo

class novelai_image_mcp.nai.response.NovelAIImage(filename: 'str', data: 'bytes')[源代码]

基类:object

参数:
filename: str
data: bytes
class novelai_image_mcp.nai.response.GenerationEvent(event_type: 'str', sample_index: 'int', step_index: 'int', generation_id: 'str', sigma: 'float', image: 'NovelAIImage')[源代码]

基类:object

参数:
event_type: str
sample_index: int
step_index: int
generation_id: str
sigma: float
image: NovelAIImage
novelai_image_mcp.nai.response.check_status(status_code, content)[源代码]

Raise the domain error associated with an HTTP status.

The NovelAI error code (body statusCode/code, or the HTTP status when the body carries none) and its official explanation are attached to the raised exception and appended to its message.

参数:
返回类型:

None

novelai_image_mcp.nai.response.parse_zip_images(content)[源代码]
参数:

content (bytes)

返回类型:

tuple[NovelAIImage, ...]

class novelai_image_mcp.nai.response.MessagePackStreamParser[源代码]

基类:object

Incrementally parse NovelAI's big-endian length-prefixed MessagePack.

feed(chunk)[源代码]
参数:

chunk (bytes)

返回类型:

tuple[GenerationEvent, ...]

finish()[源代码]
返回类型:

None

novelai_image_mcp.nai.response.parse_messagepack_events(content)[源代码]
参数:

content (bytes)

返回类型:

tuple[GenerationEvent, ...]

novelai_image_mcp.nai.response.parse_messagepack_images(content)[源代码]
参数:

content (bytes)

返回类型:

tuple[NovelAIImage, ...]

备注

上面列出的异常类被导入到 response 中,以便在 check_status 中抛出; 它们记录在定义它们的模块 novelai_image_mcp.nai.exceptions 下(见下一小节)。

novelai_image_mcp.nai.exceptions

领域异常层级:

Typed NovelAI domain failures.

Every exception optionally carries the NovelAI error code (HTTP status or API-supplied stream code) and, when documented, NovelAI's official explanation — see nai.errors. The code and explanation are appended to the message (so they reach MCP tool callers and the CLI) and exposed as attributes for programmatic handling.

exception novelai_image_mcp.nai.exceptions.NovelAIError(message, *, code=None, explanation=None)[源代码]

基类:Exception

Base class for NovelAI failures.

code is the NovelAI error code when known (None for transport, timeout, or local validation failures that carry no server code); explanation is NovelAI's official explanation for documented codes.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIProviderError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIError

NovelAI rejected or failed the request.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIValidationError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIProviderError

The request is invalid.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIAuthenticationError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIProviderError

Credentials are missing, invalid, or expired.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIInsufficientCreditsError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIProviderError

The account has insufficient Anlas or no subscription.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIConcurrencyError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIProviderError

The account hit a concurrency or rate limit.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAITimeoutError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIError

A request exceeded its timeout.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAITransportError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIError

The request could not reach NovelAI.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIResponseError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIError

NovelAI returned malformed or unsupported data.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

exception novelai_image_mcp.nai.exceptions.NovelAIImageError(message, *, code=None, explanation=None)[源代码]

基类:NovelAIError

An input or output image is malformed or unsupported.

参数:
  • message (str)

  • code (int | str | None)

  • explanation (str | None)

返回类型:

None

novelai_image_mcp.nai.errors

错误体解析与官方错误码说明:ErrorInfo、 OFFICIAL_CODE_EXPLANATIONS、explain、parse_error_body。

NovelAI error-body parsing and official error-code explanations.

Every error raised toward NovelAI's API carries the error code and — where documented — NovelAI's official explanation text (see OFFICIAL_CODE_EXPLANATIONS). Codes sent inside MessagePack stream errors by the API itself ({code, message} events) are passed through verbatim.

novelai_image_mcp.nai.errors.OFFICIAL_CODE_EXPLANATIONS: dict[int, str] = {400: 'invalid request (validation failed)', 401: 'authentication failed (missing, invalid, or expired credentials)', 402: 'active subscription or Anlas required', 409: 'request conflicted with server state', 429: 'rate limit or concurrency limit reached'}

Official error codes documented by NovelAI's API docs (https://api.novelai.net/docs) and the official FAQ. 5xx are deliberately folded into the generic provider-error bucket rather than enumerated.

class novelai_image_mcp.nai.errors.ErrorInfo(code, message, raw)[源代码]

基类:object

Normalized error payload extracted from a NovelAI error body.

参数:
code: int | str | None
message: str
raw: str
novelai_image_mcp.nai.errors.explain(code)[源代码]

Return NovelAI's official explanation for a documented error code.

Undocumented codes (including API-supplied MessagePack stream codes) return None — the API's own message is then the best explanation.

参数:

code (int | str | None)

返回类型:

str | None

novelai_image_mcp.nai.errors.parse_error_body(content)[源代码]

Extract (code, message) from a NovelAI error body.

NovelAI returns JSON in several shapes — {"statusCode", "message"}, {"code", "message"}, {"error": ...}, or a bare {"message"} — or, on some legacy paths, raw text. Falls back to the decoded text when neither a code nor a message field is present.

参数:

content (bytes)

返回类型:

ErrorInfo

novelai_image_mcp.nai.service

create_novelai_client 工厂 + NovelAIConfigLike 协议。该工厂接收一个 类 settings 对象与一个 httpx.AsyncClient,返回接线完整的 NovelAIClient。

High-level NovelAI service construction for the MCP server and CLI consumers.

A duck-typed config object (NovelAIConfigLike Protocol) keeps the nai package decoupled from the MCP wrapper. The wrapper's NovelAISettings (pydantic-settings, env-driven) satisfies this protocol structurally; see novelai_image_mcp.settings.

class novelai_image_mcp.nai.service.NovelAIConfigLike(*args, **kwargs)[源代码]

基类:Protocol

Structural shape of any object supplying NovelAI client configuration.

token: str | None
username: str | None
password: str | None
image_base_url: str
account_base_url: str
legacy_image_base_url: str
timeout: float
vibe_cache_entries: int
novelai_image_mcp.nai.service.create_novelai_client(config, *, http_client=None)[源代码]

Create a complete client from a configuration object.

Accepts either a token or a complete username/password pair. Pass a shared http_client when the caller (e.g. the MCP lifespan) wants connection pooling across requests; otherwise the client owns a private session.

参数:
返回类型:

NovelAIClient

官方错误码

该客户端抛出的每个 NovelAI 错误都带有错误 code(HTTP 状态码,或 API 自身的 流式错误码),并且在有文档的情况下带有 NovelAI 的官方说明。两者都会追加到消息中, 并作为异常的属性暴露:

错误码

含义(官方)

400

无效请求(校验失败)

401

认证失败

402

需要有效订阅或 Anlas

409

请求冲突

429

速率限制 / 并发限制

5xx

NovelAI 上游错误

所有异常都派生自 NovelAIError,并暴露 .code / .explanation(对于传输、超时以及不带服务端错误码的本地校验失败,两者均为 None)。解析辅助函数见 novelai_image_mcp.nai.errors 模块。

参见