Stable Diffusion WebUI 登录与鉴权：API 密钥、账号密码与接口调用

2023 年 11 月 16 日（讨论页面显示的日期；检索接口按 UTC 记为 15 日，以页面为准），AUTOMATIC1111 的官方仓库讨论区出现了关于 API 授权的实际问题：用户已经用 --api --api-auth admin:12345 启动了 WebUI，却不知道接口请求应该如何携带凭据。讨论中给出的解决办法是，在请求头中发送 Basic Authorization；这也说明了一个容易混淆的点：Stable Diffusion WebUI 的“登录”和“API 鉴权”不是同一种入口配置。下面按本地 WebUI、API 文档页和客户端调用三条路径，说明密钥放在哪里、请求怎么发，以及怎样确认鉴权已经成功。

本文把官方仓库 README、官方仓库讨论区中的操作记录放在一起说明；涉及 API 请求格式的内容来自讨论区用户实际验证过程，不把它们写成所有版本都保证不变的官方承诺。

先分清：WebUI 登录、API 鉴权和模型下载密钥

Stable Diffusion WebUI 是运行在浏览器中的 Gradio 图形界面。你需要配置的是本机 WebUI 的访问权限，以及调用 /sdapi/v1/ 接口时的凭据。Hugging Face 或 Civitai 的 token 属于下载受限模型的凭据，和 --api-auth 不是同一个东西。

官方仓库 README 将 Stable Diffusion WebUI 定义为基于 Gradio 的 Web 界面，并列出了文生图、图生图、放大、扩展等能力。它同时说明项目提供一键安装和运行脚本，但仍需自行安装 Python 和 Git。也就是说，启动脚本不是完整的系统环境；第一次运行前仍要准备 Python、Git、模型文件，以及足够的磁盘和显存空间。

前置条件：先确认你的启动方式和端口

1. 安装 Python 和 Git。打开终端运行 python --version 和 git --version，确认两条命令都能输出版本号；仓库 README 明确把 Python 和 Git 列为运行前仍需安装的基础环境。

2. 确认 WebUI 能正常启动，并且浏览器能打开首页。启动后记下地址栏中的主机名和端口；下面示例使用官方仓库讨论区出现的 127.0.0.1:7860，如果你修改了端口，必须同步替换请求 URL。

3. 决定是否需要 API。若只是使用文生图、图生图等网页功能，可以先不启用 API；若准备让脚本、插件或自己的客户端调用接口，再配置 --api 和 --api-auth，并把凭据放在客户端请求中。

启用 API：把账号密码写进启动参数

官方仓库讨论区记录的实际启动方式，是在 WebUI 的启动参数中加入 --api，再用 --api-auth 指定“用户名:密码”。原文示例如下：

--nowebui --api --api-auth admin:12345

这表示启用 API，并将访问凭据设为用户名 admin、密码 12345。如果你的环境通过 COMMANDLINE_ARGS 传入参数，讨论区还给出了这样的完整写法：

set COMMANDLINE_ARGS= --xformers --no-half-vae --api --api-auth user:pass --nowebui --port 58189

Windows 用户可以把这行放进实际使用的 webui-user.bat 启动流程；macOS 或 Linux 则应把同样的参数放进对应启动脚本的参数位置。这里最重要的不是照抄 user、pass 或端口号，而是确认三项：存在 --api、存在 --api-auth、账号和密码中间使用英文冒号。

不要把真实密码提交到 Git 仓库，也不要把包含密码的启动脚本公开发布。讨论区里的用户回复（社区经验，非官方公告）提醒：Basic Authorization 并不天然适合暴露在公网；如果 WebUI 需要被其他机器访问，应优先限制监听地址和网络访问范围。

在 /docs 页面确认凭据是否生效

启用 API 后，在浏览器打开 WebUI 的 API 文档页。按讨论区中的实际路径，进入 /docs，找到 /sdapi/v1/txt2img 接口，点击接口右侧的锁图标，在弹出的输入框中填写用户名和密码，然后提交请求。

如果页面能正常返回生成结果或接口响应，说明账号密码已经与启动时设置的 --api-auth 对上。若点击锁图标后仍然无法授权，先不要反复改密码：重新检查启动命令中的英文冒号、用户名和密码是否与页面填写内容完全一致，并确认 WebUI 进程是在修改参数后重新启动的。

API 文档页还有一个实用价值：它可以直接验证接口路径和鉴权方式，而不必先写完整客户端。对于只想确认“能不能调用”的用户，先在 /docs 手动操作，比一开始就排查 JSON 参数或显卡环境更容易。

客户端请求：Authorization 头应该怎样写

讨论区用户验证过，Basic Authorization 的值是“用户名:密码”经过 Base64 编码后的结果。例如用户名是 admin、密码是 12345，则原文给出的示例是：

Authorization: Basic YWRtaW46MTIzNDU=

客户端请求应使用类似下面的结构：

curl -X POST http://127.0.0.1:7860/sdapi/v1/txt2img 
  -H "Authorization: Basic YWRtaW46MTIzNDU=" 
  -H "Content-Type: application/json" 
  -d '{"prompt":"a cat","steps":4,"width":512,"height":512}'

这里的关键是：Authorization 属于 HTTP 请求头，不是放在 URL 查询字符串里，也不是放在 JSON 的 prompt 字段中。讨论区还记录了 Python 客户端的写法，即使用 requests.post(url='{URL}/sdapi/v1/txt2img', json=payload, auth=('user', 'password'))；请求库会替你完成用户名密码到 Authorization 头的转换。

如果你使用自己的程序，建议先按讨论区的方式在 /docs 中验证一次，再写客户端。请求被拒绝（鉴权失败或无权限）时，优先检查凭据和请求头；返回 404 时，优先检查 API 路径是否完整、端口是否正确，以及是否真的用 --api 启用了接口。

常见卡点：报错和对应处理

“404 not found”：讨论区中的提问者把用户名和密码直接 POST 到 127.0.0.1:7860/login，得到 404。处理方法不是继续请求 /login，而是改用 API 文档中的 /sdapi/v1/txt2img 路径，并按上面的方式携带 Authorization 头。

请求成功但没有看到 API 锁图标：检查启动参数中是否有 --api，以及修改参数后是否重新启动 WebUI。讨论区中另一个用户提供了 --api-auth user:pass 的启动参数组合，说明该参数应在启动阶段设置，而不是在网页的普通登录框里临时填写。

浏览器能打开 WebUI，但客户端一直提示未授权：浏览器登录状态和 API 的 --api-auth 是两套机制。先在 /docs 的锁图标中测试；若浏览器接口也无法通过，再检查启动命令中的密码是否包含空格、引号或中文标点。

把模型下载 token 填成了 API 密码：Hugging Face、Civitai token 用于下载模型，不能替代 --api-auth。在云端或容器文档中，Vast.ai 的说明也把 HF_TOKEN、CIVITAI_TOKEN 与 Web/API 鉴权分开；这类平台文档可作为“不同 token 不要混用”的对照，但具体变量不能直接套用到本地 A1111。

怎么算成功，以及如何安全收尾

成功标志有三个：浏览器能进入 /docs；点击 /sdapi/v1/txt2img 的锁图标后能填写凭据并得到接口响应；使用客户端发送带 Authorization 头的请求时，不再收到未授权或路径错误。若只想验证鉴权，先用讨论区里的简短客户端结构请求一个低分辨率测试图即可。

配置完成后，把 COMMANDLINE_ARGS 中的真实密码替换为你自己生成的值，并限制 WebUI 只监听本机或受信任网络。若必须对外开放，至少确认前面使用了 HTTPS、反向代理或网络访问控制——这是社区讨论中反复出现的经验共识，官方仓库并未就此单独发布安全公告，本文不把它当官方结论。

延伸阅读可以先看 AUTOMATIC1111/stable-diffusion-webui 官方仓库，再对照 API 授权讨论 #13993 与 API key 讨论 #7362。需要部署到云端时，再阅读 Vast.ai 的 Image Generation 文档，但不要把它的平台 token 或端口配置误当成 A1111 的通用设置。