API 端点

本页汇总 OPL 数据空间中最重要的 API 端点，帮助你把模型能力接入自动化流程、脚本和第三方工具。当前实现仍在持续演进，但下面这些接口已经足够支撑大多数集成场景。

认证

访问 API 时需要认证。最常见方式是使用 Bearer Token：

在 OPL 数据空间的 设置 > Account 里生成 API Key
或者使用 JWT（Web UI 内部也会用它访问同一批接口）

完整开启与生成流程请看 API Keys。

组织感知授权

在启用了组织的部署中，API 认证仍然会按当前用户的有效权限和归属组织来解析。不要因为某个 API Key 之前能访问某个租户数据，就假设在组织迁移、组织停用或角色变化后它依然有效。

代理前置场景的替代请求头

如果 OPL 数据空间前面已经有一个会消费 Authorization 头的反向代理，可以改用自定义请求头传 API Key。默认是 x-api-key，管理员也可以通过 CUSTOM_API_KEY_HEADER 修改。详见 Behind a reverse proxy that consumes Authorization?。

Swagger 文档

important

只有把 ENV 环境变量设为 dev，Swagger 文档才会开放。

应用	文档路径
Main	`/docs`

重要 API 端点

📜 获取全部模型

Endpoint：GET /api/models
说明：返回通过 OPL 数据空间创建或接入的全部模型

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/models

💬 Chat Completions

Endpoint：POST /api/chat/completions
说明：兼容 OpenAI Chat Completions，用于访问 OPL 数据空间中的 Ollama、OpenAI 兼容模型以及自定义函数模型

在组织感知部署中，即便端点路径不变，不同租户下的模型可见性、附加知识库、direct connections 与功能开关也可能不同。

curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "llama3.1",
        "messages": [
          {
            "role": "user",
            "content": "Why is the sky blue?"
          }
        ]
      }'

🔮 Anthropic Messages API

OPL 数据空间同时提供兼容 Anthropic Messages API 的端点，因此面向 Anthropic SDK、Claude Code 等工具的客户端，也可以直接走 OPL 数据空间。

Endpoints：POST /api/message、POST /api/v1/messages
认证方式：支持 Authorization: Bearer YOUR_API_KEY，也支持 Anthropic 风格的 x-api-key: YOUR_API_KEY

curl -X POST http://localhost:3000/api/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o",
        "max_tokens": 1024,
        "messages": [
          {
            "role": "user",
            "content": "Why is the sky blue?"
          }
        ]
      }'

如果你用的是 Anthropic SDK，base_url 应指向 http://localhost:3000/api，而不是 /api/v1，因为 SDK 会自动补上 /v1/messages。

Claude Code 配置方式

export ANTHROPIC_BASE_URL="http://localhost:3000/api"
export ANTHROPIC_API_KEY="YOUR_OPEN_WEBUI_API_KEY"
claude

或在 ~/.claude/settings.json 中写入：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:3000/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_OPEN_WEBUI_API_KEY"
  }
}

这会让 Claude Code 的请求经过 OPL 数据空间的认证与访问控制层，同时使用你在 OPL 数据空间中配置好的模型。

信息

所有在 OPL 数据空间中配置的模型都可以通过这个端点访问，包括 Ollama、本地模型和自定义函数模型。model 字段应使用 OPL 数据空间中看到的模型 ID。

🔧 Filters / Functions 与 API 请求的关系

直接调用 API 时，Filters（Functions）的行为与 Web UI 内部调用并不完全一致。

Filter 执行概览

Filter Function	WebUI 请求	直接 API - stable (`main`)	直接 API - pre-release (`dev`)
`inlet()`	✅	✅	✅
`stream()`	✅	✅	✅
`outlet()`	✅	❌ `/api/chat/completions` 不会内联执行	⚠️ 只在特定条件下内联执行

inlet() 适合做：

限流
请求日志
输入校验

关于 direct API 的 outlet() 行为

对纯 API 调用者而言，如果你需要通过 HTTP 拿到 outlet() 处理后的结果，当前最稳妥的方式仍然是：

先调用 /api/chat/completions
再调用 /api/chat/completed

即便在 dev 分支中，outlet() 某些情况下可以在 /api/chat/completions 后内联执行，它也不会直接重写当前 HTTP 响应体。

`/api/chat/completed`

这是 direct API 集成最可靠的 outlet() 执行端点：

Endpoint：POST /api/chat/completed
说明：对一段完成的聊天 payload 执行 outlet()，并返回经过过滤后的结果

curl -X POST http://localhost:3000/api/chat/completed \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "llama3.1",
        "messages": [
          {"role": "user", "content": "Hello"},
          {"role": "assistant", "content": "Hi! How can I help you today?"}
        ],
        "chat_id": "optional-uuid"
      }'

🦙 Ollama API 代理

如果你想直接与 Ollama 模型交互，包括 embedding 生成和原生 prompt streaming， OPL 数据空间提供了透明代理：

Base URL：/ollama/<api>

生成补全

curl http://localhost:3000/ollama/api/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Why is the sky blue?"
  }'

列出模型

curl http://localhost:3000/ollama/api/tags \
  -H "Authorization: Bearer YOUR_API_KEY"

生成 Embeddings

curl -X POST http://localhost:3000/ollama/api/embed \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "input": ["OPL 数据空间 is great!", "Let'\''s generate embeddings."]
  }'

OpenAI-compatible Responses API

curl -X POST http://localhost:3000/ollama/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "input": "Why is the sky blue?"
  }'

这使得 Codex、Claude Code 等客户端可以直接以 Responses API 方式访问由 Ollama 托管的模型，而无需额外配置单独的 OpenAI 兼容服务。

🧩 Retrieval Augmented Generation（RAG）

RAG 相关 API 允许你上传文件、构建知识库，并把这些内容用于聊天补全。

上传文件

Endpoint：POST /api/v1/files/
Query Parameters：
- process：是否抽取内容并计算 embedding
- process_in_background：是否异步处理

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@/path/to/your/file" \
  http://localhost:3000/api/v1/files/

注意

文件上传默认是异步处理。上传接口会先返回 file ID，但内容抽取和 embedding 仍在后台进行。若你在处理完成前就把文件加入知识库，会得到 400，提示内容为空。

查看文件处理状态

Endpoint：GET /api/v1/files/{id}/process/status
支持 stream=true 以 SSE 方式订阅状态更新

状态值：

Status	说明
`pending`	仍在处理
`completed`	处理成功
`failed`	处理失败

把文件加入知识库

Endpoint：POST /api/v1/knowledge/{id}/file/add

curl -X POST http://localhost:3000/api/v1/knowledge/{knowledge_id}/file/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "your-file-id-here"}'

important

加入知识库前，务必先确认文件状态已经是 completed。

实用建议

纯 API 集成如果依赖 outlet()，请坚持两步调用：/api/chat/completions + /api/chat/completed
上传文件后，先轮询处理状态，再入库
在组织化部署中，把 API Key 始终当成“代表某个用户”的凭据
对于代理较重的网络环境，优先考虑自定义 API Key 请求头

认证​

Swagger 文档​

重要 API 端点​

📜 获取全部模型​

💬 Chat Completions​

🔮 Anthropic Messages API​

Claude Code 配置方式​

🔧 Filters / Functions 与 API 请求的关系​

Filter 执行概览​

/api/chat/completed​

🦙 Ollama API 代理​

生成补全​

列出模型​

生成 Embeddings​

OpenAI-compatible Responses API​

🧩 Retrieval Augmented Generation（RAG）​

上传文件​

查看文件处理状态​

把文件加入知识库​

实用建议​

认证