image-generator-sd-webui

图像生成器（sd-webui API）

概述

通过 REST API 驱动 Stable Diffusion WebUI / Forge 服务，以枚举可用资源、运行 txt2img、轮询进度并中断任务。scripts/ 下的 Shell 入口共用一个 curl 客户端。生成文件模式使用 Python 3 辅助程序解码并验证 PNG 文件、保存元数据，且仅返回精简的路径清单。

服务连接

开始操作前，先向用户确认服务 URL（以及可选的 HTTP Basic Auth）。将它们作为环境变量传递给每个脚本：

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. 生成 — 调用 scripts/generate.sh，传入请求 JSON 文件，并将 --output-dir 指向调用方会话暂存目录下的绝对路径。此脚本会在本地保存图像和元数据，并返回精简的路径清单。
5. （可选）跟踪进度 — 生成运行期间（在另一个 Shell / 后台运行），调用 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
Embedding	scripts/list.sh embeddings	GET /sdapi/v1/embeddings

scripts/list.sh <kind> 会逐行输出每个条目的规范英文标识符 — 可通过管道传递给 column、fzf 等工具。添加 --json 可获取原始 JSON。

列出选项后，将其呈现给用户（如果列表较短，请使用带枚举选项的 ask_user）。对于模型，优先使用完整的 title（其中包含哈希后缀，例如 anima/animaika_v36.safetensors [d50fb5b9a0]），而不是 model_name，因为 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. 读取精简的 stdout 清单：

   {"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 推导该目录。请将提示词放在请求文件中，而不是 shell 参数中。无需使用 shell 重定向或自定义 HTTP 客户端。

发生故障时，命令会以非零状态退出，且不会输出成功清单。失败的批次会被删除；如果清理失败，stderr 会指出保留的部分输出目录。通过 SIGINT/SIGTERM 中断时也会尝试清理；SIGKILL 无法执行清理。成功生成的文件会一直保留，直到调用方在交付后清理暂存目录。使用清单前，调用方必须检查退出状态。

对于现有集成，省略 --output-dir 会保留旧版行为：将完整的 API JSON 响应（包括 base64 图像）输出到 stdout。两种模式都支持通过 stdin 传入请求（-）。面向 Agent 的交付请使用文件模式，避免将 base64 放入模型上下文。

重要行为说明：

• samples_format 预设：sd-webui/Forge 会在应用 override_settings 之前验证 samples_format，因此，如果服务器的持久值不受支持（例如 avif），txt2img 就会失败。generate.sh 会预先向 /sdapi/v1/options 执行 POST，将 samples_format=png，并且冗余地注入 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 会一直阻塞，直到图像准备就绪。脚本使用 600s 的 curl 超时；可通过 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 绘图）

要在单个网格中比较参数变化，请使用 x/y/z plot 脚本。实现前，请阅读 references/xyz-plot.md，了解完整的 19 参数 API 结构、轴类型索引的发现方法、Prompt S/R 语法，以及特定变体的注意事项。

跟踪进度

从另一个终端调用（或先在后台运行 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

优先在 txt2img 请求中使用 override_settings，而不是 options set——override_settings 仅对当前请求生效，并会在调用后恢复；而 options set 会全局持久生效，影响所有其他客户端。

提示词工程

此技能不会生成或优化提示词。当用户请求提示词帮助时：

1. 检查是否有其他可用的提示词工程 Agent 技能（按名称搜索，例如：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 — 每个 txt2img 请求字段，包括 HiRes-fix、refiner、Forge 专属扩展（forge_additional_modules、forge_inference_memory、forge_preset），以及 override_settings 键。
• references/xyz-plot.md — X/Y/Z 绘图脚本 API：19 参数结构、轴类型索引、Prompt S/R 格式、通过 script-info 在运行时发现，以及特定变体的注意事项。

仅在构建复杂请求或遇到需要深入调查的错误时阅读这些资料。