image-generator-sd-webui

画像生成（sd-webui API）

概要

REST API を通じて Stable Diffusion WebUI / Forge サーバーを操作し、利用可能なリソースの一覧表示、txt2img の実行、進行状況の確認、ジョブの中断を行います。scripts/ 内のシェルエントリポイントは、共通の curl クライアントを使用します。生成ファイルモードでは、Python 3 のヘルパーを使用して PNG ファイルをデコードおよび検証し、メタデータを保存します。返されるのは簡潔なパスマニフェストのみです。

サーバー接続

作業を始める前に、サーバー URL（および任意の HTTP Basic 認証）をユーザーに確認してください。すべてのスクリプトに環境変数として渡します。

export SD_WEBUI_URL="http://localhost:7860"   # required, no trailing slash
export SD_WEBUI_USER=""                       # optional, HTTP Basic Auth
export SD_WEBUI_PASS=""                       # optional

設定されていない場合、スクリプトは認証なしで http://localhost:7860 をデフォルトとして使用します。

接続の簡易テスト（成功時は OK <url> を返し、失敗時はゼロ以外の終了コードで終了します）：

scripts/probe.sh

ワークフロー

1. 確認 — サーバーに接続できることを確認します（scripts/probe.sh）。失敗した場合は、正しい URL／認証情報をユーザーに尋ねます。
2. 一覧表示して選択 — 選択肢となるリソース（モデル、モジュール、サンプラー、スケジューラー、スタイル）を一覧表示し、ユーザーに選んでもらいます。選択内容は API の英語の name／title／model_name としてそのまま取得してください。sd-webui は完全一致で照合するため、翻訳や名前の変更はしないでください。
3. プロンプト — 肯定プロンプト、否定プロンプト、および追加パラメーター（ステップ数、CFG、サイズ）を取得します。これらの入手方法については「プロンプトエンジニアリング」を参照してください。
4. 生成 — リクエスト JSON ファイルと、呼び出し元のセッション用ステージングディレクトリ内にある絶対パスの --output-dir を指定して、scripts/generate.sh を呼び出します。画像とメタデータがローカルに保存され、簡潔なパスマニフェストが返されます。
5. （任意）進行状況の追跡 — 生成の実行中に（別のシェル／バックグラウンドで）、scripts/progress.sh を呼び出して progress（0～1）、eta_relative、state を表示します。
6. （任意）キャンセル — scripts/cancel.sh を呼び出して、現在のジョブを中断します。

タスク

利用可能なリソースの一覧表示

ユーザーの要望	コマンド	API エンドポイント
チェックポイント（モデル）	scripts/list.sh models	GET /sdapi/v1/sd-models → {title, model_name, hash, ...} の配列
追加モジュール（TE／VAE、Forge 専用）	scripts/list.sh modules	GET /sdapi/v1/sd-modules → {model_name, ...} の配列
サンプラー	scripts/list.sh samplers	GET /sdapi/v1/samplers → {name, aliases} の配列
スケジューラー	scripts/list.sh schedulers	GET /sdapi/v1/schedulers → {name, label} の配列
スタイルプリセット	scripts/list.sh styles	GET /sdapi/v1/prompt-styles → {name, prompt, negative_prompt} の配列
アップスケーラー	scripts/list.sh upscalers	GET /sdapi/v1/upscalers
LoRA	scripts/list.sh loras	GET /sdapi/v1/loras
埋め込み	scripts/list.sh embeddings	GET /sdapi/v1/embeddings

scripts/list.sh <kind> は各エントリの正規の英語識別子を1行ずつ出力します。column、fzf などにパイプできます。生の JSON を取得するには --json を追加してください。

一覧表示後、選択肢をユーザーに提示してください（一覧が短い場合は、列挙型を使って ask_user を呼び出します）。モデルでは、model_name よりも、ハッシュの接尾辞を含む完全な title（例：anima/animaika_v36.safetensors [d50fb5b9a0]）を優先してください。title のほうが曖昧さがないためです。ユーザーがハッシュなしのファイル名だけを指定した場合は、list.sh models で確認し、API に送る前に正確な title に置き換えてください。スケジューラーについては、list.sh schedulers は人が読める label（例：Beta）を出力します。txt2img の scheduler フィールドでは、label と小文字の name（beta）のどちらも使用できます。

画像の生成（txt2img）

1. JSON リクエストを作成します。必須フィールドは prompt です。推奨フィールドは negative_prompt、steps、cfg_scale、width、height、sampler_name、scheduler、styles（スタイル名の配列）、および override_settings.sd_model_checkpoint（モデルタイトル）／override_settings.forge_additional_modules（モジュール名の配列、Forge のみ）です。すべてのフィールドについては references/txt2img-parameters.md を参照してください。
2. 実行します：

   scripts/generate.sh "/absolute/session/request.json" --output-dir "/absolute/session/generated"
   

3. コンパクトな標準出力マニフェストを読み取ります：

   {"image_paths":["/absolute/session/generated/generation.ABC1234567/image-0001.png"],"metadata_path":"/absolute/session/generated/generation.ABC1234567/metadata.json"}
   

4. 以降のファイル処理や配信では、すべての image_paths エントリを絶対パスとして使用します。生成の詳細が必要な場合に限り、metadata_path を読み取ります。メタデータには images を除くすべての API レスポンスフィールドが含まれ、info は変更されずに保持されます（通常は JSON でエンコードされた文字列です）。

ファイルモードでは、curl と jq に加えて Python 3 が必要です。グリッドを含む、返されたすべての画像がレスポンス順に保存されます。呼び出しごとに一意の名前が付いた非公開のバッチサブディレクトリが作成されるため、繰り返しの呼び出しや同時呼び出しでファイルが上書きされることはありません。スペースを含むパスにも対応しています。現在のセッションでは出力ディレクトリを明示的に指定してください。プロセス全体で共有される SESSION_ID や TMPDIR から出力先を導出しないでください。プロンプトはシェル引数ではなく、リクエストファイル内に記述してください。シェルのリダイレクトやカスタム HTTP クライアントは不要です。

失敗時は、成功マニフェストを出力せずにゼロ以外の終了コードで終了します。失敗したバッチは削除されます。クリーンアップに失敗した場合は、保持された部分出力ディレクトリが標準エラー出力に示されます。SIGINT／SIGTERM による割り込み時もクリーンアップを試みますが、SIGKILL ではクリーンアップを実行できません。成功したファイルは、配信後に呼び出し元がステージングディレクトリをクリーンアップするまで残ります。マニフェストを使用する前に、呼び出し元は終了ステータスを確認する必要があります。

既存のインテグレーションでは、--output-dir を省略すると、base64 画像を含む従来形式の完全な API JSON レスポンスが標準出力に返されます。標準入力からのリクエスト（-）は、どちらのモードでも使用できます。エージェント向けに配信する場合は、base64 がモデルコンテキストに入らないよう、ファイルモードを使用してください。

重要な動作に関する注意：

• samples_format の事前固定：sd-webui／Forge は override_settings を適用する前に samples_format を検証するため、サーバーの永続値がサポートされていない値（例：avif）の場合、txt2img は失敗します。generate.sh は事前に /sdapi/v1/options に samples_format=png を POST し、さらに冗長ではありますが override_settings.samples_format=png も注入します。⚠️ 事前固定によってサーバーの永続的なデフォルト値が "png" に変更されます。override_settings_restore_afterwards では元に戻せません。異なるデフォルト値を期待するクライアントとサーバーを共有している場合は、後から手動で復元してください：scripts/options.sh set samples_format '"webp"'。PNG 以外の形式が必要な場合は、ローカルで変換してください（下記の「別の形式への変換」を参照）。
• generate.sh は override_settings_restore_afterwards: true を強制的に有効にするため、その他の override_settings キー（モデルチェックポイント、モジュール、VAE）は設定に残りません。
• 生成は同期処理です。画像の準備が完了するまで POST はブロックされます。スクリプトの curl タイムアウトは 600 秒です。SD_WEBUI_TIMEOUT=900 scripts/generate.sh ... で変更できます。

別の形式への変換

ユーザーが PNG 以外の形式（WebP、AVIF、JPEG など）での出力を希望する場合、サーバー上で別の samples_format を再度有効にしようとしないでください。代わりに、埋め込まれた sd-webui の生成メタデータを保持したままローカルで変換します。

1. format-converter.sh と copy-info.sh の両方が PATH 上で利用できるか確認します（例：command -v format-converter.sh && command -v copy-info.sh）。
2. 両方が利用できる場合は、PNG に対して format-converter.sh を実行します。パラメーターを引き継ぐため、内部で copy-info.sh が呼び出されます。現在の使い方を確認するには format-converter.sh -h を実行してください。
3. どちらか一方でも見つからない場合は、ヘルパープロジェクトを一度インストールするようユーザーに案内してください：https://github.com/jim60105/sd-image-format-converter。システム依存関係を手動でセットアップする必要があるため、自動インストールはできません。インストール後は両方のスクリプトが PATH 上で利用できるようになり、-h で使い方を確認できます。

複数軸の比較（X/Y/Z プロット）

1つのグリッド内でパラメーターのバリエーションを比較するには、x/y/z plot スクリプトを使用します。実装する前に、完全な19引数のAPI構造、軸タイプのインデックスの確認方法、Prompt S/Rの構文、バリアント固有の注意点について、references/xyz-plot.mdをお読みください。

進行状況の追跡

別のターミナルから呼び出すか、先にgenerate.shの呼び出しをバックグラウンド化して&を付けて実行します。

scripts/progress.sh                  # one-shot, prints JSON
scripts/progress.sh --watch          # poll every 1s until progress reaches 1.0 or state.job is empty
scripts/progress.sh --watch --interval 2
scripts/progress.sh --field progress # just the numeric 0..1 value
scripts/progress.sh --field state.job

エンドポイント：GET /sdapi/v1/progress?skip_current_image=true。主なレスポンスフィールド：

• progress — 現在のジョブの完了割合を示す0〜1の浮動小数点数です。
• eta_relative — 残り時間の推定値（秒）です。
• state.job — 現在のジョブ名です（アイドル時は空文字列）。
• state.sampling_step / state.sampling_steps — 現在のステップ番号／合計ステップ数です。
• current_image — 生成中の画像のbase64 PNGプレビューです（レスポンスサイズを抑えるため、スクリプトではskip_current_image=trueにより省略されます。必要であればcurlで直接取得できます）。

キャンセル

scripts/cancel.sh         # POST /sdapi/v1/interrupt — stop current job, return current partial result
scripts/cancel.sh --skip  # POST /sdapi/v1/skip — skip current job in a batch

注：interruptは協調的な処理です。サンプラーに次のステップで停止するよう指示します。実行中のgenerate.sh呼び出しは、モデルがそれまでに生成した内容（多くの場合、使用可能ではあるものの未完成の画像）を返します。txt2img呼び出しでHTTPエラーが発生することはありません。

グローバルオプション（上級者向け）

scripts/options.shはGET /sdapi/v1/optionsとPOST /sdapi/v1/optionsをラップします。

scripts/options.sh get                                # print all options as JSON
scripts/options.sh get sd_model_checkpoint            # print one key
scripts/options.sh set sd_model_checkpoint '"<title>"' # set one key (value is JSON; string must be quoted)
scripts/options.sh set-json '{"k1":"v1","k2":"v2"}'   # set multiple keys
scripts/options.sh refresh-checkpoints                # POST /sdapi/v1/refresh-checkpoints

options setよりも、txt2imgリクエスト内のoverride_settingsを優先してください。override_settingsはリクエスト単位で適用され、呼び出し後に元に戻ります。一方、options setはグローバルに保存され、他のすべてのクライアントに影響します。

プロンプトエンジニアリング

このスキルでは、プロンプトの生成や改善は行いません。ユーザーがプロンプトの作成支援を求めた場合：

1. プロンプトエンジニアリングに対応する別のエージェントスキルが利用可能か確認します（sd-prompt-builder、danbooru-prompt、image-prompt-*などの名前で検索します）。利用可能であれば、そのスキルに委任します。
2. そうでなければ、ユーザーにプロンプトを明示するよう求めるか、自然言語による説明をそのまま受け取り、promptフィールドに渡します。Danbooruタグやスタイル修飾子を独自に作り出してはいけません。

参考資料

• references/api-endpoints.md — sd-webui / Forgeの全エンドポイントリファレンスです。このスキルが使用するすべてのエンドポイントのリクエスト／レスポンス形式に加え、関連する便利なエンドポイント（/sdapi/v1/memory、/sdapi/v1/png-infoなど）も記載しています。
• references/txt2img-parameters.md — HiRes-fix、refiner、Forge固有の拡張機能（forge_additional_modules、forge_inference_memory、forge_preset）、override_settingsのキーを含む、txt2imgリクエストのすべてのフィールドを記載しています。
• references/xyz-plot.md — X/Y/ZプロットスクリプトのAPIです。19引数の構造、軸タイプのインデックス、Prompt S/R形式、script-infoによる実行時の確認方法、バリアント固有の注意点を記載しています。

複雑なリクエストを組み立てる場合や、より詳しい調査が必要なエラーが発生した場合にのみ、これらをお読みください。