novelai_image_mcp.tools¶
11 个 MCP 工具函数。每个工具都是 async 的,并返回 MCP 内容块的 list
(Image + 文本路径)。依赖 —— NovelAIClient、
NovelAISettings 以及每请求的路由上下文 —— 以
Depends(...) 提供者(deps.py)的形式传入,因此它们按请求解析,
从不出现在工具的输入 schema 中。
参见
工具参考 中的叙述性文档,覆盖每个工具的 每个参数、默认值与示例。
novelai_image_mcp.tools.generate¶
MCP tools: text-to-image, image-to-image, and inpainting.
- async novelai_image_mcp.tools.generate.generate_image(prompt, negative_prompt='', model=None, width=None, height=None, steps=None, scale=None, sampler=None, seed=0, n_samples=1, quality=True, uc_preset=0, cfg_rescale=0.0, smea=None, smea_dynamic=None, auto_smea=False, straight_alpha=False, prefer_brownian=True, noise_schedule=NoiseSchedule.KARRAS, character_prompts=None, references=None, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), app=Depends(get_app_context))[源代码]¶
Generate one or more images from a text prompt (text-to-image).
Supports NovelAI V3 / V4 / V4.5 / V5 models. Pass
referencesas a list of base64-encoded PNG/JPEG strings to apply vibe transfer (V4/V4.5 only - V5 does not support vibe transfer yet and rejects it). V5 models additionally accept English/Japanese natural-language prompts and thestraight_alphaflag for true transparency (pair it with prompt tags such astransparent backgroundorhas alpha).character_promptsenables multi-character composition with per-character prompts and center coordinates (x, y in 0.1-0.9). Dimensions are rounded up to the nearest multiple of 64.- 参数:
prompt (str)
negative_prompt (str)
model (Model | None)
width (int | None)
height (int | None)
steps (int | None)
scale (float | None)
sampler (Sampler | None)
seed (int)
n_samples (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=8)])])
quality (bool)
uc_preset (Literal[0, 1, 2, 3])
cfg_rescale (float)
smea (bool | None)
smea_dynamic (bool | None)
auto_smea (bool)
straight_alpha (bool)
prefer_brownian (bool)
noise_schedule (NoiseSchedule)
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
- async novelai_image_mcp.tools.generate.image_to_image(prompt, image, negative_prompt='', model=None, strength=0.3, noise=0.0, width=None, height=None, steps=None, scale=None, sampler=None, seed=0, n_samples=1, quality=True, uc_preset=0, noise_schedule=NoiseSchedule.KARRAS, cfg_rescale=0.0, extra_noise_seed=None, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), app=Depends(get_app_context))[源代码]¶
Generate a new image conditioned on an input image (image-to-image).
imageis a base64-encoded PNG/JPEG.strength(0.01-0.99) controls how far the result diverges from the input;noise(0-0.99) adds extra variation. The model must match the input image domain.- 参数:
prompt (str)
image (str)
negative_prompt (str)
model (Model | None)
strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.01), Le(le=0.99)])])
noise (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=0.99)])])
width (int | None)
height (int | None)
steps (int | None)
scale (float | None)
sampler (Sampler | None)
seed (int)
n_samples (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=8)])])
quality (bool)
uc_preset (Literal[0, 1, 2, 3])
noise_schedule (NoiseSchedule)
cfg_rescale (float)
extra_noise_seed (int | None)
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
- async novelai_image_mcp.tools.generate.inpaint(prompt, image, mask, negative_prompt='', model=None, strength=0.3, noise=0.0, width=None, height=None, steps=None, scale=None, sampler=None, seed=0, n_samples=1, quality=True, uc_preset=0, noise_schedule=NoiseSchedule.KARRAS, cfg_rescale=0.0, extra_noise_seed=None, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), app=Depends(get_app_context))[源代码]¶
Inpaint (locally redraw) a region of an image.
imageandmaskare base64-encoded PNG/JPEG; the mask marks the region to regenerate (non-transparent pixels are redrawn). Requires an inpainting model such asnai-diffusion-4-5-full-inpaintingornai-diffusion-5-full-inpainting.- 参数:
prompt (str)
image (str)
mask (str)
negative_prompt (str)
model (Model | None)
strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.01), Le(le=0.99)])])
noise (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=0.99)])])
width (int | None)
height (int | None)
steps (int | None)
scale (float | None)
sampler (Sampler | None)
seed (int)
n_samples (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=8)])])
quality (bool)
uc_preset (Literal[0, 1, 2, 3])
noise_schedule (NoiseSchedule)
cfg_rescale (float)
extra_noise_seed (int | None)
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
novelai_image_mcp.tools.enhance¶
MCP tools: upscale, Director tools, and ControlNet annotation.
- async novelai_image_mcp.tools.enhance.annotate_image(image, model, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), app=Depends(get_app_context))[源代码]¶
Annotate an image with a ControlNet preprocessor.
imageis a base64-encoded PNG/JPEG.modelis one of:hed(palette swap),midas(form lock / depth),fake_scribble(scribbler),mlsd(building control),uniformer(landscaper). The returned image is the annotation (e.g. a line-art map) suitable for use as a ControlNet condition in a subsequent generation.- 参数:
image (str)
model (ControlNetModel)
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
- async novelai_image_mcp.tools.enhance.director_tool(tool, image, prompt='', defry=0, emotion=None, emotion_level=EmotionLevel.NORMAL, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), features=Depends(get_effective_features), app=Depends(get_app_context))[源代码]¶
Apply a NovelAI Director tool to an image.
toolis one of:lineart,sketch,bg-removal,declutter,colorize,emotion.imageis a base64-encoded PNG/JPEG. Theemotiontool additionally requires anemotionname (e.g.happy,sad) and accepts anemotion_level(0-5, where 0 is normal intensity and 5 is weakest).promptguidescolorizeandemotion;defry(0-10) sharpens line art.emotionandemotion_levelare experimental: they are served only to requests that opt in through the insiders header (X-MCP-Insiders: experimental-tools=true). Without that opt-in, passing either one fails with aToolError; a non-defaultemotion_levelalone counts as passing it. Both parameters stay visible in this tool's schema either way, because a tool schema is published when the server starts and cannot vary per request.- 参数:
tool (DirectorTool)
image (str)
prompt (str)
defry (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=10)])])
emotion (Emotion | None)
emotion_level (EmotionLevel)
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
- async novelai_image_mcp.tools.enhance.upscale_image(image, factor=4, routing=Depends(get_routing_context), route_scoped_output=Depends(get_route_scoped_output), app=Depends(get_app_context))[源代码]¶
Upscale an image 4x using NovelAI's standalone upscaler.
imageis a base64-encoded PNG/JPEG. NovelAI's standalone upscaler offers a single 4x step — the API exposes no scaling factor — sofactoronly accepts4. The upscaler runs on the V5 model configured byNOVELAI_UPSCALE_MODEL(defaultnai-diffusion-5-full) and consumes Anlas based on the source resolution.- 参数:
image (str)
factor (Literal[4])
routing (RoutingContext)
route_scoped_output (bool)
app (AppContext)
- 返回类型:
novelai_image_mcp.tools.account¶
MCP tools: account queries and Anlas cost estimation.
- async novelai_image_mcp.tools.account.estimate_anlas_cost(width, height, steps, n_samples=1, model=Model.V4_5, action=Action.GENERATE, strength=None, smea=None, smea_dynamic=None, auto_smea=False, opus=False)[源代码]¶
Estimate the Anlas cost of a generation without calling the API.
Mirrors NovelAI's public web-client cost formula.
actionis one ofgenerate,img2img,infill(inpaint). Forimg2img,strength(0.01-0.99) scales the cost proportionally.smea/smea_dynamic/auto_smeaapply the SMEA multiplier.opusgrants a free sample when the request is within Opus limits. Returns{"anlas": <cost>, "opus_free_sample": <bool>}.This is a pure price calculation. It needs no image or mask, and it does not verify that the combination is runnable -- an
infillestimate with a non-inpainting model still returns a price. The generation tools enforce those requirements.Note: on V5 models, Opus free generations are capped by NovelAI's refillable "battery" usage limit (normal resolution, <=28 steps); once exhausted the API silently bills Anlas instead of erroring. The subscription response does not expose how much of that battery is left, so this estimate always reports the paid cost.
- 参数:
width (int)
height (int)
steps (int)
n_samples (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=8)])])
model (Model)
action (Action)
strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.01), Le(le=0.99)])] | None)
smea (bool | None)
smea_dynamic (bool | None)
auto_smea (bool)
opus (bool)
- 返回类型:
- async novelai_image_mcp.tools.account.get_subscription(client=Depends(get_client))[源代码]¶
Return the account subscription details and Anlas balance.
The shape mirrors NovelAI's
/user/subscriptionresponse. The keys observed on a live account aretier(0 = free, 1 = starter, ...),active,expiresAt,accountType,isGracePeriod,isNewCustomer,isPaypal,paymentProcessor,paymentProcessorData,perks(maxPriorityActions,startPriority,contextTokens,unlimitedMaxPriority,moduleTrainingSteps) andtrainingStepsLeft(fixedTrainingStepsLeft,purchasedTrainingSteps). Use this to inspect the active plan before a generation.- 参数:
client (NovelAIClient)
- 返回类型:
- async novelai_image_mcp.tools.account.get_user_data(client=Depends(get_client))[源代码]¶
Return the authenticated account's user data.
Includes
email,accountChain(registration source), and thepriorityepoch. Useful to confirm which account the server is authenticated as before issuing generation commands.- 参数:
client (NovelAIClient)
- 返回类型:
novelai_image_mcp.tools(注册入口)¶
MCP tool registration.
Importing this package imports every tool module; each module decorates the shared server instance imported from ..server as a side effect of import, so there is no registration function to call. server.py imports this package at the bottom of the module, after mcp exists.