API Open WebUI: как отправлять запросы к своим моделям из кода

Open WebUI обычно воспринимают как веб-интерфейс для чата, но у него есть собственный API. Через него скрипт, бот или другая программа может отправить запрос к тем же моделям, что подключены в вашем Open WebUI, в том числе к моделям через шлюз. Ниже разберём, как включить ключ, какие эндпоинты вызывать и чем «open webui api» отличается от обращения к шлюзу напрямую.

Описание ниже опирается на документацию Open WebUI (раздел API Endpoints и страница про API-ключи). В документации сказано, что часть интерфейса экспериментальная и может меняться, поэтому названия пунктов меню и эндпоинтов проверяйте в вашей версии.

Два ключа, которые легко перепутать

Когда Open WebUI подключён к шлюзу, в схеме участвуют два разных ключа:

1. Ключ шлюза fetch_.... Он вписан в подключение Open WebUI (адрес https://api.zukko.pro/v1) и уходит только на сервер шлюза. Как подключить, описано в статье Open WebUI: подключение к Zukko↗.
2. Ключ пользователя Open WebUI. Его выдаёт сам Open WebUI, и именно его ваш код отправляет на адрес вашего Open WebUI.

Ваш скрипт никогда не должен знать ключ шлюза: он стучится в Open WebUI, а тот уже обращается к шлюзу. Это удобно, когда ключ шлюза должен остаться на сервере, а пользователям нужен только доступ к интерфейсу.

Как получить ключ Open WebUI

По документации Open WebUI, ключ выдаётся в несколько шагов.

1. Администратор включает API-ключи глобально: Settings, Admin, Authentication, переключатель API Keys. Пока он выключен, ключи не создаются и не работают, даже у администраторов.
2. Обычному пользователю нужно разрешение «API Keys» в правах группы (Admin Panel, Users, Groups, Features Permissions). Администратор может создать ключ сразу.
3. Пользователь открывает свой профиль, Settings, Account, раздел API keys, нажимает Show и создаёт новый секретный ключ.

Что важно знать: у каждого аккаунта ровно один ключ. Создание нового заменяет старый, и старый перестаёт работать мгновенно. Ключ действует от имени пользователя и наследует его права. Срока действия у ключа нет, ротация делается вручную. По документации, ключи имеют вид sk- и 32 шестнадцатеричных символа.

Поэтому для каждой интеграции заведите отдельный аккаунт без прав администратора, например ci-bot, и создавайте ключ из него.

Какие эндпоинты вызывать

Адрес в примерах документации — http://localhost:3000, у вас он будет свой. Все запросы идут с заголовком Authorization: Bearer ваш_ключ.

Список моделей

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

Эндпоинт GET /api/models возвращает модели, доступные в вашем Open WebUI. Идентификатор для запроса берите именно оттуда, а не угадывайте: так вы увидите, под каким именем модель опубликована в вашей установке.

Запрос к модели

Основной эндпоинт — POST /api/chat/completions, OpenAI-совместимый.

curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [{"role": "user", "content": "Объясни, что такое кэш промптов, в двух предложениях"}]
  }'

То же самое на Python:

import requests

BASE = "http://localhost:3000"
TOKEN = "YOUR_API_KEY"

resp = requests.post(
    f"{BASE}/api/chat/completions",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "model": "claude-sonnet-5-5",
        "messages": [{"role": "user", "content": "Привет"}],
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Поскольку формат OpenAI-совместимый, можно использовать и официальный SDK, указав в base_url адрес вашего Open WebUI с суффиксом /api: клиент сам допишет /chat/completions. Если этот вариант у вас не заработает, возвращайтесь к обычному requests, как выше.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:3000/api", api_key="YOUR_API_KEY")
r = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Привет"}],
)
print(r.choices[0].message.content)

Формат Anthropic

У Open WebUI есть и Anthropic-совместимый эндпоинт POST /api/v1/messages, который принимает заголовок x-api-key или Bearer. Для Anthropic SDK адрес указывается как .../api, без /v1, иначе путь задвоится. По документации, если подключение в Open WebUI работает в OpenAI-формате (как в схеме с адресом https://api.zukko.pro/v1), запрос внутри конвертируется в chat completions и на шлюз придёт уже как OpenAI-запрос; для Claude это значит, что весь вход считается по цене входа, без скидки за кэш. Подключения, которые сами работают по Anthropic Messages API, по документации получают запрос без конвертации.

Инструменты и расход токенов

Если в Open WebUI настроены инструменты (в том числе MCP), их можно включить из API: идентификаторы передаются в поле tool_ids. Для MCP-серверов идентификатор имеет вид server:mcp:<id сервера>. Документация отдельно предупреждает: если сервер защищён OAuth, пользователь ключа должен заранее пройти авторизацию в веб-интерфейсе.

Для учёта токенов в ответе с инструментами документация разводит поля. prompt_tokens и completion_tokens относятся к последнему обращению к модели, а input_tokens и output_tokens — ко всему ответу, где обращений могло быть несколько. Если вы считаете расход по этим полям, берите вторую пару. Сверять итоговые суммы всё равно надёжнее по истории списаний в кабинете шлюза.

Кто платит и как ограничить расход

Деньги списываются с баланса шлюза по ключу fetch_..., который вписан в подключение, а не по ключу Open WebUI. Значит, любой, у кого есть ключ Open WebUI, тратит ваш баланс. Ограничьте риск на стороне шлюза: заведите отдельный ключ под Open WebUI с дневным и месячным лимитом в долларах и списком разрешённых моделей. Как это делается, написано в документации по лимитам ключей↗ и в статье как поставить лимит на API-ключ↗.

На стороне Open WebUI можно ограничить, какие маршруты доступны по ключу: настройка Endpoint Restrictions, список путей через запятую (например /api/models и /api/chat/completions). Ограничение общее для всех ключей установки.

Ошибки

• 401 — ключ Open WebUI неверный, заменён новым или аккаунт не активен.
• 403 — глобальный переключатель ключей выключен, у пользователя нет права на ключи или маршрута нет в списке разрешённых.
• Ошибки шлюза проходят насквозь: по документации Open WebUI, при отказе провайдера эндпоинт возвращает статус и текст ошибки провайдера. Поэтому 402 (не хватает баланса), 403 model_not_allowed_for_key или 429 по лимиту ключа вы увидите в ответе Open WebUI. Полный список кодов шлюза есть в справочнике chat completions↗.

Частые вопросы

Нужно ли подключать Open WebUI к шлюзу, чтобы пользоваться его API?

Нет, API работает с любыми подключёнными моделями. Но чтобы получить через него Claude, GPT или DeepSeek одним ключом, подключите шлюз как OpenAI-совместимый провайдер.

Можно ли выдать несколько ключей одному пользователю?

Нет. По документации, у аккаунта один ключ, новый заменяет старый. Для нескольких интеграций заведите несколько аккаунтов.

Чем это лучше обращения к шлюзу напрямую?

Не лучше и не хуже, это другая схема. Прямой запрос проще и даёт кэш и учёт без посредника. Через Open WebUI вы получаете учётные записи пользователей, права, фильтры и общие настройки моделей.

Где посмотреть свежий список эндпоинтов?

В документации Open WebUI и в Swagger вашей установки. По документации, Swagger доступен по пути /docs, если запустить Open WebUI с переменной окружения ENV=dev.

Чтобы попробовать, создайте ключ в кабинете↗, подключите его к Open WebUI и получите ключ пользователя по шагам выше.