Stable Diffusion WebUI 鉴权怎么配：密钥填入与接口验证

Stable Diffusion WebUI 的界面登录与 API 鉴权是两套独立的用户名密码（官方讨论与文档均把两者分开配置，别当成一个开关）。

在 2023 年 11 月 16 日的 AUTOMATIC1111 官方仓库讨论中（讨论页面显示的日期；检索接口按 UTC 记为 15 日，以页面为准），有用户贴出了 API 凭据的传递方式：先通过 --api-auth 设置“用户名:密码”，再到 /docs 页面填写——这是讨论区的用户经验、不是官方保证，实际以官方文档当前说明为准。现在最值得先核对的，恰恰是模型下载 token、WebUI 登录和 API 鉴权三者不能混用；下面按“启动时设置密钥、浏览器验证、客户端调用”的实际路径操作。

先分清要填的是哪一种凭据

Stable Diffusion WebUI 是基于 Gradio 构建的本地网页界面。不同操作使用的凭据并不相同：模型下载 token 用来取得 Hugging Face 等平台的受限模型；WebUI 登录凭据控制谁能打开界面；API 鉴权凭据则保护 /sdapi/v1/ 接口。

官方仓库的 README 将项目定义为“Stable Diffusion web UI”，并提供文生图、图生图、放大等能力。它同时说明，一键安装与运行脚本仍要求使用者自行安装 Python 和 Git，因此启动脚本并不能替代完整运行环境。

要完成的操作	凭据填写位置	应使用的内容
打开本机 WebUI	启动参数或 WebUI 登录设置	WebUI 登录用户名、密码
调用文生图 API	启动参数 --api-auth	用户名:密码
从 /docs 调试接口	接口右侧锁形按钮	与 --api-auth 相同的用户名、密码
下载受限模型	模型下载页面或平台 Token 设置	Hugging Face 等平台 token

最常见的误区，是把平台 token 填进 --api-auth。后者不是一串不可解释的 API Key，而是一组用户名和密码；程序最终会把两者组合后放进 HTTP Authorization 请求头。

前置条件：先让三项检查通过

1. 安装 Python 和 Git。打开终端运行 python --version 与 git --version，两条命令都应正常输出版本号；官方 README 明确把这两项列为运行前仍需自行安装的基础环境。

2. 确认 WebUI 已能正常启动，并能在浏览器中打开地址。官方讨论记录使用过 http://localhost:7860；如果修改了端口，应把后续地址中的 7860 换成实际端口。

3. 确认准备调用 API，而不是只做本机文生图。必须启用 API，并设置一组仅用于本服务的用户名和密码。不要把真实凭据提交到 GitHub，也不要在没有额外保护的情况下把接口暴露到公网。

启动时设置用户名和密码

官方仓库讨论区给出的完整 Windows 配置形式是：

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

这里最关键的是 --api 与 --api-auth user:pass：

• --api 开启 API 功能。
• --api-auth 设置接口凭据。
• user 和 pass 分别是用户名与密码，中间必须使用英文冒号。
• --port 58189 只是该讨论中的示例端口；本机已有固定端口时，可以沿用原来的端口配置。

在 macOS、Linux 或直接运行 Python 的环境中，可以把同一组参数传给启动入口：

python launch.py --api --api-auth user:pass

Windows 用户若使用仓库提供的批处理启动文件，也可以把参数放进 webui-user.bat 的启动命令中。不同系统脚本的写法不同，但鉴权参数本身不变。

需要单独打开浏览器界面时，不要沿用上面的 --nowebui 示例；否则程序不会启动通常的 WebUI，只提供 API 服务。此时应删除 --nowebui，保留：

python launch.py --api --api-auth user:pass

在 /docs 中完成登录验证

启动后打开：

http://localhost:7860/docs

如果使用了自定义端口，例如 58189，则打开：

http://localhost:58189/docs

在 API 文档中找到 /sdapi/v1/txt2img，点击该行右侧的锁形按钮，填入启动时设置的同一组用户名和密码。不要填写 Hugging Face token，也不要把“用户名”和“密码”拼成一个字段；需要分别填写对应位置。

提交测试请求时，页面应能在请求中加入 Authorization 请求头。官方讨论中的有效做法是使用 HTTP Basic 认证，也就是先对 用户名:密码 做 Base64 编码，再把结果放入 Authorization: Basic ...。

浏览器只是验证入口。文档页能解锁，不等于所有客户端已经自动带上凭据；脚本、插件或移动端应用仍需单独设置认证。

客户端请求要携带 Authorization

官方讨论区还记录了 Python 客户端的请求形式：

response = requests.post(url=f'{URL}/sdapi/v1/txt2img', json=payload, auth=('user', 'password'))

其中 URL 应替换成实际接口根地址，例如 http://localhost:7860；payload 则是接口要求的请求数据。这里不需要自行计算 Base64，因为 auth=('user', 'password') 会由 HTTP 客户端完成用户名和密码的编码与传递。

使用 JavaScript 客户端时，逻辑也是一致的：先读取用户名和密码，将二者以冒号连接，再进行 Base64 编码，最后写入 Authorization 请求头。不要把凭据放进 URL 查询参数，因为查询参数更容易出现在日志、浏览器历史和监控记录中。

官方讨论区还特别提醒，这一套 Basic 认证“并不安全”；该提醒针对直接暴露的接口尤其重要。只在本机使用时应限制服务监听范围；需要远程访问时，还应另外增加可信网络边界或反向代理鉴权。

常见卡点：报错出现时这样改

提示 404 not found

官方讨论中的真实报错是：用户向 127.0.0.1:7860/login 发送用户名和密码，请求失败并返回：

404 not found

这个问题不是密码错误，而是把 API 当成了网页登录接口。改为打开：

http://localhost:7860/docs

找到 /sdapi/v1/txt2img，点击锁形按钮，再填写用户名和密码。不要继续向 /login 提交表单。

/docs 不要求凭据

另一条真实讨论记录是：

at localhost/docs it doesnt want API keys or something, anyone can do API requests.

这种情况下，先确认启动命令里确实同时包含 --api 和 --api-auth user:pass，然后完全退出旧进程，再重新启动。修改 webui-user.bat 或 webui-user.sh 后，也要确认修改的是当前实际使用的启动脚本，而不是另一个副本。

服务启动了，却找不到 /docs

先确认请求地址中的端口与启动参数一致。例如命令写了 --port 58189，浏览器就不能继续访问默认的 7860。对应地址应为：

http://localhost:58189/docs

怎么算已经配置成功

完成配置后，应同时观察到三个结果：

1. 使用自定义端口启动后，对应的 WebUI 首页可以正常打开。
2. http://localhost:<端口>/docs 中能看到 /sdapi/v1/txt2img，并能通过锁形按钮输入凭据。
3. 客户端向 /sdapi/v1/txt2img 发起请求时，认证信息由 Authorization 请求头携带，而不是通过 /login 表单或 URL 参数传递。

只看到 /docs 页面还不够；真正的完成标志是同一组用户名和密码在文档页与客户端请求中都能通过验证。

官方入口与延伸阅读

• AUTOMATIC1111 Stable Diffusion WebUI 官方仓库：查看安装说明、启动脚本及项目更新。
• API 授权讨论 #13993：查看 /docs 锁形按钮与 Basic Authorization 的实际验证记录。
• API Keys 讨论 #7362：对照 --api-auth user:pass、自定义端口和客户端认证写法。
• GitHub 官方文档：如果保存启动脚本时需要使用 GitHub 账号，可从这里进入认证与账户文档；它与 WebUI 的 API 密码不是同一套凭据。

参考来源

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