SD WebUI API 兼容#

Xinference 在 OpenAI 兼容的图像 API 之外，还提供兼容 Stable Diffusion WebUI 的接口。扩展工作流支持 Diffusers 的 Stable Diffusion 和 SDXL 模型。其他图像引擎仍提供基础生成接口，但不实现 ControlNet、ADetailer 或 Hires Fix。

安装#

在运行此工作流的每个 Worker 上安装可选依赖:

pip install 'xinference[sdapi]'

MediaPipe、FaceXLib 和 InsightFace 等预处理器专用依赖，仅在选择对应预处理器时加载。RealESRGAN 和 ADetailer 会在首次使用时下载权重。源码和模型权重使用各自的许可证；内置预处理器的声明和许可证位于 xinference/thirdparty/controlnet。

生成图像#

在 model 或 override_settings.sd_model_checkpoint 中填写已启动图像模型的 UID。例如:

curl http://localhost:9997/sdapi/v1/txt2img \
  -H 'Content-Type: application/json' \
  -d '{"model":"sd-model","prompt":"a (small cat:1.2)",
       "seed":42,"steps":20,"width":512,"height":512,
       "batch_size":2,"n_iter":1,"request_id":"example-job"}'

响应包含 base64 编码的 images、实际生效的 parameters，以及带有种子和生成元数据的 info 对象。batch_size 是每轮迭代生成的图像数量，n_iter 是迭代次数。通常每生成一张图像就递增种子；若 subseed_strength 不为零，则主种子保持不变，改为递增子种子。

加权提示词支持圆括号、显式权重、方括号、转义分隔符，以及按 CLIP token 分块处理的长提示词。SDXL 使用两个文本编码器，并提供其流水线所需的池化条件向量。

使用 Hires Fix 时，将 enable_hr 设为 true，并设置 hr_scale``（默认为 2）、``hr_upscaler``（例如 ``Latent、Lanczos 或 R-ESRGAN 4x+）；还可以设置 hr_second_pass_steps。denoising_strength 必须大于零且不超过一。图像先生成并放大，再通过第二轮图生图处理细化。

POST /sdapi/v1/img2img 的 init_images 接受原始 base64、图像 data URL 或公开的 HTTP(S) 图像 URL。支持 mask、mask_blur、inpainting_mask_invert、inpaint_full_res 和 inpaint_full_res_padding。resize_mode 可设为 0（缩放）、1（裁剪填满）或 2（适配并填充边缘）。URL 下载会拒绝私有地址，并验证每次重定向；图像响应大小限制为 64 MiB。

ControlNet 与 ADetailer#

通过 alwayson_scripts 传入 WebUI 脚本:

{
  "ControlNet": {
    "args": [{"enabled": true, "module": "canny", "model": "controlnet-canny",
              "image": "<base64 image>", "weight": 1.0,
              "pixel_perfect": true, "resize_mode": "Crop and Resize"}]
  },
  "ADetailer": {
    "args": [true, {"ad_model": "face_yolov8n.pt", "ad_prompt": "[PROMPT]"}]
  }
}

选择已启动模型所属系列列出的 ControlNet 模型。支持多个单元，各自配置条件权重和引导起止位置。SD 1.5 支持仅参考图工作流。预处理器包括 Canny、深度、OpenPose、MLSD 和线稿等；Worker 上必须具备对应检测器的依赖和权重。此 SDAPI 移植不包含仅使用张量的 IP-Adapter 工作流。

ADetailer 在图像生成或 Hires Fix 之后运行，支持检测掩码、局部重绘，以及 [PROMPT]、[SEP]、[SKIP] 提示词指令。

LoRA#

注册一个自定义图像模型，设置 model_family: "lora"，并提供本地 model_uri 或包含一个 safetensors 文件的模型仓库。然后在提示词中通过 <lora:model-name:0.8> 引用它。metadata.ss_output_name 可以指定另一个别名。启用 override_settings.strict 后，无法解析的 LoRA 会被拒绝。请求结束后会移除适配器，即使推理失败也会清理。

已注册 LoRA 的 model_uri 也可以使用 CivitAI 的 HTTPS 下载 URL。如需鉴权，请在 Worker 环境中设置 CIVITAI_API_TOKEN。令牌不会转发给重定向后的 CDN 主机。下载先写入临时文件，再通过原子替换保存。

查询与取消#

以下接口与图像生成接口使用相同的身份验证要求：

  • GET /sdapi/v1/loras 和 GET /sdapi/v1/upscalers 列出可用的适配器和放大器。

  • GET /controlnet/model_list、GET /controlnet/module_list 和 GET /controlnet/control_types 查询运行中的模型和预处理器。

  • POST /controlnet/detect 接受 controlnet_module、controlnet_input_images``（或别名 ``controlnet_images）、controlnet_processor_res 及阈值参数。

  • GET /sdapi/v1/progress?request_id=example-job 返回请求进度。

  • POST /sdapi/v1/interrupt 接受 {"model":"sd-model","request_id":"example-job"} 并取消该请求。此接口要求明确指定模型和请求 ID，不会停止所有请求。

ComfyUI 不属于此 API 兼容层。