Connect Open WebUI to AvalAI

Open WebUI can use AvalAI through its OpenAI-compatible connection while keeping model discovery, RAG, images, and audio under separate feature settings. This guide establishes stable Chat Completions first, treats Open Responses as experimental, and shows a small authenticated Docker Compose baseline.

Validated: The public connection labels, account defaults, endpoint contract, and container paths were checked against official Open WebUI sources on 2026-08-06. Recheck the AvalAI model catalog and current Open WebUI release before deployment.

What this integration is

The request flow is:

Browser user → Open WebUI conversation and task pipeline → configured AvalAI connection → selected model

Open WebUI owns users, conversations, files, retrieval, tools, task models, and media settings. AvalAI authenticates the API requests Open WebUI makes. A working chat connection does not automatically configure embeddings, image generation, speech, or transcription.

Use this integration when you want a self-hosted multi-user chat interface. Connect directly to AvalAI from your application when you do not need Open WebUI's account, conversation, and retrieval layers.

What you need

• Docker with Compose; Docker is the officially recommended installation path for most users.
• A dedicated AvalAI API key.
• A current chat model such as gpt-5.4-mini.
• A stable random WEBUI_SECRET_KEY stored outside source control.
• A plan for the first administrator account and later registration approval before exposing the service.
• Network support for WebSocket connections so streamed chat works correctly.

The first account registered on a fresh Open WebUI data volume becomes Administrator. Later registrations start in Pending status and require administrator approval by default.

Preflight AvalAI

Confirm these values before adding the connection:

Check	Required value
OpenAI-compatible base URL	https://api.avalai.ir/v1
Required primary route	/v1/chat/completions
Recommended discovery route	/v1/models
Pilot model	gpt-5.4-mini
Optional experimental route	/v1/responses

Open WebUI verifies a connection by calling /models with Bearer authentication. Verification can fail when a provider does not expose that route even though Chat Completions works. In that case, use Model IDs (Filter) rather than changing a correct chat endpoint.

AvalAI does not currently support the gpt-transcribe or gpt-live-transcribe identifiers. Use only models currently listed for /v1/audio/transcriptions in audio settings.

Install Open WebUI

Create a private working directory and an ignored .env file containing a stable secret. Then start the validated stable image with persistent storage:

WEBUI_AUTH=True
WEBUI_SECRET_KEY=replace-with-an-independent-random-value

chmod 600 .env
docker volume create open-webui
docker run -d --name open-webui --restart unless-stopped \
  -p 127.0.0.1:3000:8080 \
  --env-file .env \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:v0.11.0
docker logs --tail=100 open-webui

Open http://localhost:3000, register the intended administrator first, and confirm the volume survives a container restart before adding provider credentials.

Connect AvalAI

Sign in as the administrator and follow this exact path:

Admin Settings → Connections → OpenAI → Add Connection

Enter:

Field	Value
URL	https://api.avalai.ir/v1
API Key	Your dedicated AvalAI key
Model IDs (Filter)	Leave empty when discovery works; otherwise add gpt-5.4-mini

Save the connection and keep its enable/disable toggle on. A manual model filter is an allowlist and discovery fallback; it does not change the actual capabilities of the model.

Chat Completions first

The primary OpenAI-compatible connection expects Chat Completions. Select gpt-5.4-mini, send a plain prompt, and verify streaming before enabling tools or attaching files.

Open Responses is separate and experimental

Open WebUI describes Open Responses support as experimental. Configure and test it separately from the stable Chat Completions connection. Both Open WebUI and the selected AvalAI model must support the request and stream shape; do not treat it as a drop-in switch for an existing chat connection.

Verify the first flow

Verify one layer at a time:

1. Confirm the container is healthy and /app/backend/data is mounted.
2. Confirm the intended first account has Administrator access.
3. Confirm the AvalAI connection is saved and enabled.
4. Confirm model discovery works or gpt-5.4-mini appears through Model IDs (Filter).
5. Start a new chat and send a plain text request with no tools or files.
6. Confirm incremental streamed output appears.
7. Send a second turn that depends on the first answer.
8. Only then test tools, vision, RAG, images, STT, or TTS one capability at a time.

If plain chat fails, do not debug the retrieval or media stack yet. First separate container health, authentication, model selection, endpoint shape, and streaming.

Supported capabilities

The primary connection and the feature-specific settings are distinct surfaces.

Status	Capability	What to expect
Direct	Model discovery	/v1/models is recommended; Model IDs (Filter) is the manual fallback.
Direct	Chat Completions	The primary OpenAI connection requires /v1/chat/completions.
Model/route dependent	Open Responses	Open WebUI support is experimental and the selected AvalAI model must support /v1/responses.
Model/route dependent	Streaming	Open WebUI, the AvalAI model, and any existing proxy must preserve the stream and WebSocket behavior.
Model/route dependent	Tools and structured output	Requires model support, compatible tools/tool_choice, and an Open WebUI tool mode that matches the model.
Model/route dependent	Vision/image input	Requires a vision-capable AvalAI model and the correct Open WebUI attachment path.
Separate configuration	Embeddings and RAG	Configure the Documents embedding settings with https://api.avalai.ir/v1, a dedicated key, and a current model such as text-embedding-v4. Retrieval also depends on extraction, chunking, storage, and permissions.
Separate configuration	Image generation	Configure the Images settings for /v1/images/generations and a current image model such as gpt-image-2; this is not inherited from chat.
Separate configuration	Speech-to-text	Configure the Audio transcription settings for /v1/audio/transcriptions and a current model such as gpt-4o-transcribe.
Separate configuration	Text-to-speech	Configure the Audio speech settings for /v1/audio/speech and a current model such as gpt-4o-mini-tts.
Separate configuration	Web search and application tools	These are Open WebUI tools or model-specific requests with their own permissions and possible extra calls.
Unsupported or unvalidated	Realtime audio and video	No source-backed AvalAI mapping was validated through the primary OpenAI connection.

Open WebUI may send extra requests for titles, tags, follow-up suggestions, task models, tools, embeddings, or media. These can consume quota even when the visible chat shows one user turn.

Run with Docker Compose

For a durable instance, use one pinned service, one volume, one private port, and the stable secret file:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.11.0
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:8080"
    volumes:
      - open-webui:/app/backend/data
    env_file:
      - .env
    environment:
      WEBUI_AUTH: "True"
      WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY}

volumes:
  open-webui:

Validate and start it without adding Ollama or another sidecar:

chmod 600 .env
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 open-webui

Do not use floating :main or :latest tags for a reproducible deployment. The tag v0.11.0 was the current stable release when this page was validated; review release notes and migrations before changing it.

Keep authentication enabled. The official quick start warns that WEBUI_AUTH=False is a one-way choice between single-user and multi-account mode. It is not appropriate for a shared instance.

Operate safely

• Keep port 3000 on loopback or a private network. If an existing reverse proxy exposes it, require authenticated TLS and preserve WebSocket upgrades.
• Register the intended administrator before inviting users. Restrict registration and review every pending account.
• Keep WEBUI_SECRET_KEY stable across container recreation; changing or omitting it logs users out and can disrupt durable session behavior.
• Use separate AvalAI keys for chat, embeddings, or media when you need independent revocation and usage attribution.
• Treat conversation history, uploaded files, retrieval indexes, provider credentials, and user records in /app/backend/data as sensitive.
• Redact API keys, authorization headers, prompts, responses, uploaded files, and personal data from logs and support bundles.

Back up the stopped data volume before an upgrade:

docker compose stop open-webui
mkdir -p backup/open-webui-data
docker cp open-webui:/app/backend/data/. backup/open-webui-data/
docker compose start open-webui

Record the current image tag. To upgrade, review release notes, change only the pinned tag, run docker compose config --quiet, pull, and recreate with the same volume and secret. To roll back, restore the prior image tag first. Restore data only while the service is stopped and only after checking migration compatibility on a copy.

Troubleshooting

Symptom	Check this layer first	Safe next action
Connection verification returns 400, 401, or 403	/v1/models, Bearer key, or provider discovery behavior	Keep the correct base URL and add the exact model to Model IDs (Filter) when only discovery fails.
Chat returns 401/403	Saved AvalAI key and connection toggle	Re-save the dedicated key and confirm the connection is enabled.
Chat returns 404	Missing /v1, wrong model, or Responses-vs-Chat mismatch	Use https://api.avalai.ir/v1 and stable Chat Completions first.
Model is absent	Filter, account tier, or stale catalog	Add one current ID to Model IDs (Filter) and start a new chat.
Plain chat works but tools fail	Function calling, tool mode, or schema	Verify model support and reduce the test to one tool.
Vision fails	Model capability or attachment path	Select a catalog-verified vision model and test one small image.
RAG fails	Embedding settings, extractor, chunks, permissions, or storage	Test embeddings separately before re-indexing a small document.
Image or audio fails	Feature-specific engine, URL, key, or model	Recheck the corresponding Images or Audio settings; chat credentials alone are insufficient.
Output is not streaming	Proxy WebSocket/SSE behavior or route mismatch	Test locally on loopback, then inspect proxy buffering and upgrades.
Users are logged out after restart	Missing or changed WEBUI_SECRET_KEY	Restore the original stable secret from secure storage.
Data disappears after restart	Missing /app/backend/data volume	Confirm the named volume mount before recreating the container.

Related AvalAI guides and official sources

AvalAI:

• API introduction
• Model catalog
• Model selection
• Embeddings
• Image generation
• Speech to text
• Text to speech
• Rate limits
• Production best practices

Open WebUI:

• Official repository
• Quick Start
• Connect a Provider
• OpenAI-Compatible Providers

Validation boundary

This guide was source-reviewed on 2026-08-06. The Markdown, route links, locale parity, pinned Compose syntax, and built-site behavior can be validated locally. This work did not pull or start Open WebUI, register an administrator, store an AvalAI key, send a live chat or media request, exercise WebSockets through a proxy, restore a backup, or test a production network. Revalidate the current release and model routes before operational use.