生成工具¶
三个从文本提示词产出图像的工具 —— 纯文生图、图像条件(img2img)与蒙版条件
(inpaint)。三者都返回一个 base64 Image 块加上保存后的文件路径。
generate_image¶
文生图。最常用的工具 —— 从一段提示词产出单张或多张图像。支持 NovelAI V3 / V4 / V4.5 / V5 模型、多角色构图与 vibe transfer(V5 拒绝 vibe transfer —— 上游尚未发布)。V5 还额外接受英文 / 日文自然语言提示词。
参数¶
名称 |
类型 |
默认值 |
说明 |
|---|---|---|---|
|
|
必填 |
正向提示词。标签之间用逗号分隔。 |
|
|
|
负向提示词(UC)。 |
|
|
|
覆盖模型 id。见 |
|
|
|
图像宽度(像素)。64 的倍数。 |
|
|
|
图像高度(像素)。64 的倍数。 |
|
|
|
采样器步数(1–50)。 |
|
|
|
CFG 比例(0–20)。 |
|
|
|
采样器 id(见 |
|
|
|
随机数种子。 |
|
|
|
图像数量(1–8)。 |
|
|
|
使用质量标签预设(V4+)。 |
|
|
|
负向提示词预设(0=heavy,1=light,2=human focus)。 |
|
|
|
CFG rescale(0–1,V4+)。 |
|
|
依模型而定 |
启用 SMEA。 |
|
|
依模型而定 |
启用动态 SMEA。 |
|
|
|
按分辨率自动选择 SMEA。 |
|
|
|
真实 alpha 通道(仅 V5;配合 |
|
|
|
优先使用布朗噪声调度(V4+)。 |
|
|
|
噪声调度( |
|
|
|
V4+ / V5 多角色构图。 |
|
|
|
V4/V4.5 vibe token( |
返回¶
list[ContentBlock] —— base64 Image + 保存路径文本。
示例¶
# Simple text-to-image
await ctx.session.call_tool("generate_image", {
"prompt": "a fox in a snowy forest, masterpiece, best quality",
"negative_prompt": "lowres, bad anatomy, watermark",
"width": 832,
"height": 1216,
"steps": 28,
"scale": 5.0,
"seed": 42,
})
多角色构图(V4+)¶
V5 支持同一套多角色机制(上游实测最多 22 个角色),所以下面的行为适用于 V4 / V4.5 / V5。
await ctx.session.call_tool("generate_image", {
"prompt": "two characters talking in a cafe",
"character_prompts": [
{"prompt": "1girl, red hair, blue eyes", "x": 0.3, "y": 0.5, "negative_prompt": ""},
{"prompt": "1boy, black hair, green eyes", "x": 0.7, "y": 0.5, "negative_prompt": ""},
],
})
x 与 y 是归一化后的中心坐标,取值范围 0.1–0.9。第一个角色始终是
画面焦点。
Vibe transfer(V4 / V4.5)¶
# 1. Encode a reference image
vibe = await ctx.session.call_tool("encode_vibe", {"reference": ref_b64})
# 2. Use the vibe as a reference
await ctx.session.call_tool("generate_image", {
"prompt": "1girl, watercolor style",
"references": [vibe],
})
完整工作流见 vibe transfer 教程。
image_to_image¶
图生图。以一张输入图像为条件产出新图像。
参数¶
名称 |
类型 |
默认值 |
说明 |
|---|---|---|---|
|
|
必填 |
正向提示词。 |
|
|
必填 |
base64 编码的输入 PNG/JPEG。 |
|
|
|
负向提示词。 |
|
|
默认值 |
模型 id。必须与输入图像的领域匹配。 |
|
|
|
0.01–0.99。偏离输入图像的程度。 |
|
|
|
0–0.99。额外的变化量。 |
|
(见 |
(相同默认值) |
|
|
|
|
噪声的独立种子(默认为 |
示例¶
await ctx.session.call_tool("image_to_image", {
"prompt": "1girl, masterpiece, smile",
"image": image_b64,
"strength": 0.4,
"noise": 0.05,
})
小技巧
strength=0.5 是不错的起点。低于 0.3 时结果看起来像对输入图像重新去噪;
高于 0.7 时它会向全新的文生图漂移。
inpaint¶
对图像的某个区域做局部重绘。区域由蒙版定义 —— 非透明像素会被重新生成。
参数¶
名称 |
类型 |
默认值 |
说明 |
|---|---|---|---|
|
|
必填 |
针对被重绘区域的提示词。 |
|
|
必填 |
base64 编码的输入 PNG/JPEG。 |
|
|
必填 |
base64 编码的蒙版。非透明 = 重绘。 |
|
|
|
针对该区域的负向提示词。 |
|
|
默认值 |
必须是 inpaint 模型(例如 |
|
(见 |
(相同默认值) |
示例¶
await ctx.session.call_tool("inpaint", {
"prompt": "1girl, masterpiece, smiling",
"image": image_b64,
"mask": mask_b64,
"model": "nai-diffusion-4-5-full-inpainting",
"strength": 0.5,
})
警告
局部重绘需要专用的 inpaint 模型。用非 inpaint 模型调用 inpaint 会返回
NovelAIValidationError。调用前可以用
is_inpaint_model(位于 nai.constants 子模块)检查。
蒙版制作的分步说明见 inpaint 教程。
另请参见¶
配置 —— 省略参数时套用的默认值