> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open WebUI

> 在 Open WebUI 中配置 Tapapi

Open WebUI 官方支持连接 OpenAI-compatible API。Tapapi 在 Open WebUI 里建议先作为文本 / Chat Provider 接入：配置 Base URL、API Key 后，通过 `/v1/models` 读取模型，再走 `/v1/chat/completions` 发起聊天请求。

<Warning>这页先覆盖 Open WebUI 的聊天模型接入。图片生成是否能在 Open WebUI UI 内直接使用，取决于你当前 Open WebUI 版本的图片功能；需要稳定图片生成时，优先用 [HTTP REST](/integrations/http-rest) 或 [n8n / Make](/integrations/n8n-make)。</Warning>

不要把 Tapapi API Key 填进公开实例、共享截图、公开环境变量或前端代码里。多人共用 Open WebUI 时，建议单独创建低额度、限定模型的 Tapapi Key。

## 推荐配置

| 字段            | 值                       |
| ------------- | ----------------------- |
| Provider type | OpenAI-compatible       |
| Base URL      | `https://tapapi.ai/v1`  |
| API Key       | Tapapi 控制台创建的 `sk-` Key |
| Model         | 控制台可用的文本模型，例如 `gpt-5.4` |
| Streaming     | 建议先关闭跑通，再按模型开启          |

## 操作步骤

1. 进入 Open WebUI 管理后台。
2. 打开 `Admin Settings` -> `Connections`。
3. 新增 OpenAI-compatible 连接。
4. 填入 Base URL 和 API Key。
5. 保存后刷新模型列表，选择 Tapapi 文本模型发一条测试消息。

## Base URL 怎么填

大多数 OpenAI-compatible 工具会在 Base URL 后自动拼接 `/chat/completions`、`/models` 等路径，因此推荐填写：

```text theme={null}
https://tapapi.ai/v1
```

如果你的 Open WebUI 版本请求到了 `/v1/v1/chat/completions`，说明工具已经自动拼了 `/v1`，把 Base URL 改成：

```text theme={null}
https://tapapi.ai
```

如果请求到了 `/chat/completions` 且返回 404，说明缺少 `/v1`，改回 `https://tapapi.ai/v1`。

## 验收方式

| 检查项  | 通过标准                                 |
| ---- | ------------------------------------ |
| 模型列表 | 能看到 Tapapi 控制台可用模型，或能手动输入模型名         |
| 聊天请求 | 简单消息能返回 `choices[0].message.content` |
| 流式输出 | 如果开启 streaming，前端能持续显示内容             |
| 用量记录 | Tapapi 控制台能看到对应调用                    |
| 排障信息 | 失败时能看到 HTTP 状态码和错误 message           |

如果流式输出异常，先关闭 streaming 跑通基础请求，再检查 Open WebUI 版本、模型是否支持流式，以及是否有代理或网关截断 SSE。

## Responses / 图片 / 视频

Open WebUI Provider 接入优先用于文本 Chat，不建议把它当作完整多模态工作流入口。

| 能力               | 建议                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| Chat Completions | Open WebUI 主线，走 `/v1/chat/completions`                                                                        |
| Responses        | 仅在 Open WebUI 当前版本和模型都确认支持时评估，不作为默认配置                                                                         |
| 图片生成             | UI 支持情况随 Open WebUI 版本变化；需要稳定生产时走 [HTTP REST](/integrations/http-rest) 或 [n8n / Make](/integrations/n8n-make) |
| 视频 API           | 受控开放，未确认模型、价格和权限前不要接入 Open WebUI                                                                              |

图片 API 的稳定入口是 `POST /v1/images/generations`，生产代码需要兼容 `data[0].url` 和 `data[0].b64_json`，并尽快转存到自己的对象存储。不要默认把 `image_urls` 当作图片生成的通用图生图参数。

视频 API 当前不是默认全量开放能力。只有控制台可见模型、价格已确认、账号有权限时，才适合按 [视频 API](/video-generation/overview) 单独评估。

## 日志和排障

OpenAI-compatible 接口失败时通常返回：

```json theme={null}
{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}
```

Tapapi 响应头会返回 `X-Oneapi-Request-Id`。如果 Open WebUI 日志能看到响应头，排障时优先保存这个字段；如果看不到，至少保存 HTTP 状态码、错误 message、模型名、Base URL、Open WebUI 用户和发生时间。

| 状态            | 建议                          |
| ------------- | --------------------------- |
| 400           | 修请求字段或模型参数                  |
| 401 / 403     | 检查 Tapapi Key、余额、权限和模型可见性   |
| 404           | 优先检查 Base URL 是否多写或少写 `/v1` |
| 429           | 等待后有限重试，检查并发和限流             |
| 临时 5xx / 网络超时 | 重试 1-2 次，仍失败则告警             |

## 常见问题

| 现象                | 优先检查                                   |
| ----------------- | -------------------------------------- |
| 模型列表为空            | API Key 是否有效；Base URL 是否多写或少写 `/v1`    |
| `model not found` | Open WebUI 中选择的模型名是否和 Tapapi 控制台一致     |
| 聊天 401            | 连接里填的是 Tapapi Key，不是 OpenAI 官方 Key     |
| 聊天 404            | Base URL 是否填成 endpoint 完整路径，或少写 `/v1`  |
| 流式卡住              | 先关闭 streaming；再检查网络代理和模型是否支持流式         |
| 图片入口不可用           | Open WebUI 版本和图片功能未确认，改用 HTTP API 单独调用 |
| 用量异常              | 检查是否多人共用同一个 Key，是否有公开实例被滥用             |

## 下一步

| 场景         | 文档                                     |
| ---------- | -------------------------------------- |
| 文本 API     | [文本生成](/text-generation/overview)      |
| 底层 HTTP 规则 | [HTTP REST](/integrations/http-rest)   |
| 图片生成       | [文生图](/image-generation/text-to-image) |
| 视频 API     | [视频 API](/video-generation/overview)   |
| 错误与重试      | [错误码与重试](/errors)                      |
| 成本控制       | [成本控制](/production/cost-control)       |

## 官方参考

* [Open WebUI: Connect a Provider](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider)