生成ツール¶
テキストプロンプトから画像を生成する 3 つのツール — 純粋な text-to-image、
画像を条件とする img2img、マスクを条件とする inpaint です。3 つとも base64 の
Image ブロックと保存されたファイルパスを返します。
generate_image¶
Text-to-image。最も一般的なツールで、プロンプト文字列から 1 枚以上の画像を生成します。 NovelAI V3 / V4 / V4.5 / V5 モデル、複数キャラクターの構図、vibe 転送に対応します (V5 は vibe 転送を拒否します — 上流では未リリース)。V5 はさらに英語 / 日本語の 自然言語プロンプトを受け付けます。
パラメーター¶
名前 |
型 |
デフォルト |
備考 |
|---|---|---|---|
|
|
必須 |
ポジティブプロンプト。タグはカンマ区切り。 |
|
|
|
ネガティブプロンプト (UC)。 |
|
|
|
モデル ID を上書き。 |
|
|
|
画像の幅 (px)。64 の倍数。 |
|
|
|
画像の高さ (px)。64 の倍数。 |
|
|
|
サンプラーのステップ数 (1–50)。 |
|
|
|
CFG スケール (0–20)。 |
|
|
|
サンプラー ID ( |
|
|
|
RNG シード。 |
|
|
|
画像の枚数 (1–8)。 |
|
|
|
品質タグのプリセットを使う (V4 以降)。 |
|
|
|
ネガティブプロンプトのプリセット (0=heavy、1=light、2=human focus)。 |
|
|
|
CFG リスケール (0–1、V4 以降)。 |
|
|
モデル依存 |
SMEA を有効化。 |
|
|
モデル依存 |
動的 SMEA を有効化。 |
|
|
|
解像度に応じて SMEA を自動選択。 |
|
|
|
真のアルファチャンネル (V5 のみ。 |
|
|
|
ブラウン運動ノイズスケジュールを優先 (V4 以降)。 |
|
|
|
ノイズスケジュール ( |
|
|
|
V4 以降 / V5 の複数キャラクター構図。 |
|
|
|
V4/V4.5 の vibe トークン ( |
戻り値¶
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 転送 (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 転送のチュートリアル を 参照してください。
image_to_image¶
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,
})
Tip
strength=0.5 が出発点として適しています。0.3 を下回ると結果は入力の再デノイズの
ように見え、0.7 を超えると新規の text-to-image に近づいていきます。
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 以外のモデルで inpaint を
呼び出すと NovelAIValidationError が返されます。呼び出す前に
is_inpaint_model (nai.constants サブモジュール内) で
確認してください。
マスク作成の手順については inpaint のチュートリアル を 参照してください。
関連項目¶
設定 — パラメーターを省略したときに適用されるデフォルト