Open WebUI API 文档：认证、端点与调用示例

更新于 2026-10-27 · gpt.boats

简答：如果你要从脚本或外部应用调用 Open WebUI，先在 Settings > Account 创建 API Key，再用 Authorization: Bearer <key> 请求 /api/models 验证认证，最后调用 POST /api/chat/completions。Open WebUI 自身 API、它连接的上游模型 API，以及 OpenAI-compatible Base URL 不是同一个入口，路径必须分开确认。

定义：Open WebUI API 是 Open WebUI 对外提供的 REST 接口集合，可通过 Bearer Token 或 JWT 调用模型、模型列表、文件、知识库和聊天补全等能力。

先试这一步：用两个请求确认 API 是否可用

本文整理自 Open WebUI 当前公开技术文档，核验时间为 2026-10-27。本站是独立的接入指南站，不是 Open WebUI 官方站。

假如你的 Open WebUI 地址是 http://localhost:3000，先把 API Key 放入环境变量，不要直接写进脚本或提交到 Git：

export OPENWEBUI_URL='http://localhost:3000'

export OPENWEBUI_API_KEY='替换为你的密钥'

第一步查询模型：

curl -sS -f "$OPENWEBUI_URL/api/models" -H "Authorization: Bearer $OPENWEBUI_API_KEY"

第二步发起一次非流式聊天请求：

curl -sS -f "$OPENWEBUI_URL/api/chat/completions" -H "Authorization: Bearer $OPENWEBUI_API_KEY" -H "Content-Type: application/json" -d '{"model":"替换为返回结果中的模型 ID","messages":[{"role":"user","content":"请用一句话说明你能做什么。"}],"stream":false}'

官方 API 文档列出了 GET /api/models 和 POST /api/chat/completions，并使用 Bearer Token 认证。模型 ID 必须换成你实例实际返回或手动配置的值，不能照抄示例中的模型名。参见 Open WebUI API Endpoints。

Open WebUI API、上游模型 API 和 Base URL 怎么区分

这是配置时最容易混淆的地方：

官方参考页将 OpenAI-compatible 聊天补全、Anthropic Messages API 和 Ollama 代理分开列出。不要把上游服务的 Base URL 直接当成 Open WebUI 自身 API 地址，也不要因为上游使用 /v1 就给 Open WebUI API 路径重复添加 /v1。参见 Open WebUI Reference。

如果你的目标是让 Open WebUI 连接某个 OpenAI-compatible 服务，连接表单中的 URL 应以该服务文档为准。官方连接指南说明，Open WebUI 面向标准协议，而不是为每个供应商固定写死一套私有接口。

如何启用 API Key 并创建密钥

API Key 是否能创建，取决于实例管理员设置和你的账户权限。官方文档给出的基本流程如下：

1. 管理员进入 Settings > Admin > Authentication，打开 API Keys 全局开关并保存。
2. 非管理员用户还需要管理员授予 API Keys 功能权限，通常在用户组或默认权限中配置。
3. 普通用户点击左下角头像，进入 Settings > Account。
4. 展开 API keys 区域，点击 Create new secret key，然后复制密钥。

Open WebUI 文档说明，API Key 会继承创建者的角色和群组权限；同一账户通常只有一个 API Key，重新创建会替换旧密钥。文档还说明，API Key 没有自动过期机制，轮换需要手动完成。因此不要把“创建成功”理解成密钥具备独立的细粒度权限或自动失效时间。详细步骤见 Open WebUI API Keys。

如果页面没有 API keys 区域，先点击 Secrets 旁边的 Show；如果仍然没有，检查管理员是否打开全局开关，以及非管理员账户是否拥有相应功能权限。

最小调用示例：curl、Python 和 JavaScript

curl：查询模型并发送聊天请求

curl -sS -f "$OPENWEBUI_URL/api/models" -H "Authorization: Bearer $OPENWEBUI_API_KEY"

curl -sS -f "$OPENWEBUI_URL/api/chat/completions" -H "Authorization: Bearer $OPENWEBUI_API_KEY" -H "Content-Type: application/json" -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"你好"}],"stream":false}'

把 MODEL_ID 替换为模型查询结果中的真实 ID。-f 会让 curl 在 HTTP 错误时返回失败，便于脚本发现 401、403 或 404，而不是把错误响应误当成成功结果。

Python：显式处理超时和 HTTP 错误

import os
import requests

base_url = os.environ["OPENWEBUI_URL"].rstrip("/")
api_key = os.environ["OPENWEBUI_API_KEY"]
model = os.environ["OPENWEBUI_MODEL"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

response = requests.post(
f"{base_url}/api/chat/completions",
headers=headers,
json={"model": model, "messages": [{"role": "user", "content": "你好"}], "stream": False},
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

示例通过 rstrip 去掉 Base URL 末尾斜杠，再拼接 Open WebUI 的固定路径，避免出现双斜杠。实际返回字段可能随接口或版本变化，生产代码应先记录状态码和响应体，再按当前接口结构解析。

JavaScript fetch：读取非流式结果

const baseUrl = process.env.OPENWEBUI_URL.replace(/\/$/, "");
const apiKey = process.env.OPENWEBUI_API_KEY;
const model = process.env.OPENWEBUI_MODEL;

const response = await fetch(`${baseUrl}/api/chat/completions`, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model,
messages: [{ role: "user", content: "你好" }],
stream: false
})
});

if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data.choices?.[0]?.message?.content);

流式响应怎么处理

聊天请求使用 stream: true 时，客户端不能只调用一次 response.json() 后等待完整 JSON，而应按响应流读取数据。Open WebUI API 文档同时说明聊天补全支持流式和非流式请求。

浏览器或 Node.js 中可以先确认响应成功，再读取 response.body：

const response = await fetch(`${baseUrl}/api/chat/completions`, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model,
messages: [{ role: "user", content: "分三点介绍 Open WebUI" }],
stream: true
})
});

if (!response.ok || !response.body) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { value, done } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value, { stream: true }));
}

流式内容的具体事件格式应以你当前实例返回的响应为准。排查中断时，分别观察“请求是否建立”“是否收到首个数据块”“中途是否断开”三个位置：如果没有首个数据块，优先查认证、模型和上游连接；如果中途断开，再查反向代理、超时和客户端读取逻辑。

OpenAI-compatible 连接：URL、模型和 /models 验证

如果你是在 Open WebUI 后台连接一个 OpenAI-compatible 服务，进入 Settings > Admin > Connections，在对应连接中填写 URL、API Key 和 Model IDs。官方连接文档以 OpenAI 的 https://api.openai.com/v1 作为示例，但其他服务的 Base URL、认证方式和模型 ID 必须以对应服务的公开文档为准，不能套用。

连接页面的 Verify Connection 通常会请求上游的 /models。官方文档特别提醒：有些服务没有 /models，或者认证方式不是标准 Bearer，因此验证失败并不必然代表聊天接口不可用。此时可在 Model IDs 中手动加入真实模型 ID，再保存连接。

配置时按以下顺序检查：

1. 检查 Base URL：确认它是服务要求的根地址，是否已经包含 /v1 由上游文档决定。
2. 检查路径拼接：不要把 Open WebUI 自身的 /api/chat/completions 与上游 Base URL 混在一起。
3. 检查模型 ID：使用上游实际接受的模型或部署名称，不要只看展示名称。
4. 检查 /models：如果服务不提供该端点，改为手动添加模型 ID。
5. 检查容器网络：如果 Open WebUI 在 Docker 中，localhost 指向容器自身，不一定指向宿主机服务。

Open WebUI 官方指南还列出了模型列表请求超时配置；慢启动或高延迟环境可以依据当前文档调整相关配置，但不应把某个超时时间当成所有部署的固定值。参见 OpenAI-Compatible 连接指南。

常见错误排查表：401、403、404 和模型不存在

官方 API Key 文档将 401 重点归因于密钥格式、密钥被新密钥替换、账户状态等问题；403 则需要检查全局开关、账户权限和端点限制。排错时先确认状态码，再看响应体，不要只根据网页端是否能登录来判断 API 是否可用。

权限、安全和扩展接口注意事项

Open WebUI API Key 的权限来自创建者账户，因此更适合使用专门的服务账户或权限较小的账户，而不是直接使用管理员账户。官方文档还提供 API Key Endpoint Restrictions，可限制密钥能够访问的路径；但该限制是实例级配置，不是每个密钥独立配置。

安全自查可以按以下清单完成：

• 密钥只放在环境变量、密钥管理服务或受控配置中。
• 不要把密钥写进前端公开代码、截图、日志和 Git 仓库。
• 如果怀疑泄露，创建新密钥或删除现有密钥，并同步更新调用方。
• 定期确认账户角色、群组权限和 API 路由限制仍符合实际需要。
• 对外暴露 Open WebUI 时，优先使用 HTTPS、反向代理和访问控制。

除了聊天和模型列表，官方 API 参考还覆盖文件上传、知识库、RAG、工具调用、MCP 和模型管理等接口。这些功能可能需要额外权限或实例配置，建议先完成模型查询和一次聊天请求，再逐项扩展，避免把多个变量同时引入排错过程。参见 API Endpoints 文档。

一条可执行的接入顺序

1. 确认 Open WebUI 实例地址能在浏览器正常打开。
2. 由管理员启用 API Keys；非管理员同步确认功能权限。
3. 在 Settings > Account 创建或复制当前 API Key。
4. 用 GET /api/models 验证 Bearer Token 和实例路径。
5. 从返回结果中选择真实模型 ID。
6. 用 POST /api/chat/completions、stream:false 发起最小请求。
7. 基础请求成功后，再启用流式、文件、知识库、工具或 MCP。
8. 若要连接外部模型服务，再单独配置 OpenAI-compatible Base URL，并按上游文档核对路径与模型名。

这条顺序的核心是一次只验证一层：先验证 Open WebUI 认证，再验证模型，再验证聊天，最后才处理上游协议和高级能力。

常见问题

Open WebUI API 的 Base URL 应该填到哪里？

如果你调用的是 Open WebUI 自身 API，使用实例根地址，例如 http://localhost:3000/，再拼接 /api/models 或 /api/chat/completions。如果你是在 Open WebUI 后台添加上游模型服务，Base URL 应填写上游服务文档要求的地址，是否包含 /v1 不能一概而论。

Open WebUI 的 API Key 使用什么请求头？

官方文档的标准方式是 Authorization: Bearer <API_KEY>。如果实例位于会占用 Authorization 的反向代理之后，管理员也可以配置自定义 x-api-key 请求头，具体以当前实例的 CUSTOM_API_KEY_HEADER 配置为准。

为什么 Verify Connection 失败，但模型可能仍然能聊天？

Verify Connection 通常会调用上游的 /models。有些上游没有该端点，或使用非标准认证，所以验证会失败。可以在连接设置中手动添加真实 Model ID，然后直接用最小聊天请求验证。

Open WebUI API 返回 401 怎么办？

先确认请求头格式为 Authorization: Bearer <key>，再确认密钥没有被同一账户新创建的密钥替换，并检查请求地址确实是 Open WebUI 实例。不要只根据浏览器登录状态判断 API Key 是否有效。

Open WebUI API Key 会自动过期吗？

当前公开 API Key 文档说明没有自动过期机制，轮换需要手动完成。但实例版本、部署策略和权限设置可能变化，生产环境仍应以当前账户页面和官方文档为准。

可以直接把 OpenAI SDK 的 Base URL 指向 Open WebUI 吗？

能否直接使用取决于 SDK 请求路径和 Open WebUI 当前兼容接口。先确认 SDK 最终请求的路径，再决定 Base URL 是否包含 /v1；如果 SDK 固定拼接 /v1，而 Open WebUI 接口使用 /api/chat/completions，就需要使用适配层或改用匹配的兼容接口，不能盲目重复拼接。

相关阅读

• Continue 配置 OpenAI API 的步骤与报错排查
• LangChain 接入 OpenAI 兼容 API 的 Python 方法
• OpenAI API 401 错误的 Key、权限与白名单排查
• 模型不存在和接口路径错误的 404 排查

参考资料

1. Open WebUI API Endpoints（docs.openwebui.com）
2. OpenAI-Compatible / Open WebUI（docs.openwebui.com）
3. API Keys / Open WebUI（docs.openwebui.com）
4. Reference / Open WebUI（docs.openwebui.com）
5. OpenAI / Open WebUI（docs.openwebui.com）