From 5f84f777200d955366c0fc67e24fb208a4891b8a Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 1 Jan 2026 14:03:45 +0100 Subject: [PATCH 1/5] env vars --- .../image-generation-and-editing/usage.md | 8 --- docs/features/web-search/jina.md | 4 +- docs/getting-started/env-configuration.mdx | 47 +++++++++++++++- docs/troubleshooting/connection-error.mdx | 54 +++++++++++++++++-- docs/troubleshooting/rag.mdx | 22 +++++++- 5 files changed, 119 insertions(+), 16 deletions(-) diff --git a/docs/features/image-generation-and-editing/usage.md b/docs/features/image-generation-and-editing/usage.md index 2d777f113..0861de5cd 100644 --- a/docs/features/image-generation-and-editing/usage.md +++ b/docs/features/image-generation-and-editing/usage.md @@ -7,21 +7,13 @@ Before you can use image generation, you must ensure that the **Image Generation ## Using Image Generation -### Method 1 - 1. Toggle the `Image Generation` switch to on. 2. Enter your image generation prompt. 3. Click `Send`. ![Image Generation Tutorial](/images/tutorial_image_generation_2.png) -### Method 2 - -![Image Generation Tutorial](/images/tutorial_image_generation.png) -1. First, use a text generation model to write a prompt for image generation. -2. After the response has finished, you can click the Picture icon to generate an image. -3. After the image has finished generating, it will be returned automatically in chat. :::tip diff --git a/docs/features/web-search/jina.md b/docs/features/web-search/jina.md index 728e74a4e..cf83d8230 100644 --- a/docs/features/web-search/jina.md +++ b/docs/features/web-search/jina.md @@ -57,7 +57,8 @@ To enable the Jina web search integration, follow these steps in the Open WebUI 2. **Navigate to Web Search Settings:** Go to the **Admin Panel**, then click on **Settings** > **Web Search**. 3. **Select Jina as the Search Engine:** In the "Web Search Engine" dropdown menu, select **Jina**. 4. **Enter Your API Key:** Paste your Jina API key into the **Jina API Key** input field. -5. **Save Changes:** Scroll down and click the **Save** button to apply the changes. +5. **(Optional) Enter Jina API Base URL:** If you need to use a specific endpoint (e.g., for EU data processing), enter it in the **Jina API Base URL** field. Default is `https://s.jina.ai/`. +6. **Save Changes:** Scroll down and click the **Save** button to apply the changes. ### 3. Environment Variable Configuration @@ -66,6 +67,7 @@ For Docker-based deployments, you can configure the Jina integration using an en Set the following environment variable for your Open WebUI instance: - `JINA_API_KEY`: Your Jina API key. +- `JINA_API_BASE_URL`: (Optional) Custom Jina API endpoint. **Example Docker `run` command:** diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 613c1fcc3..6e74c2145 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -165,6 +165,13 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Description: Enables or disables the folders feature, allowing users to organize their chats into folders in the sidebar. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `FOLDER_MAX_FILE_COUNT` + +- Type: `int` +- Default: `100` +- Description: Sets the maximum number of files processing allowed per folder. +- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > General > Folder Max File Count**. + #### `ENABLE_NOTES` - Type: `bool` @@ -504,7 +511,7 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model- - Type: `bool` - Default: `True` -- Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs. +- Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs (e.g., Ollama Embeddings). #### `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA` @@ -518,6 +525,12 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model- - Default: `True` - Description: Controls SSL/TLS verification specifically for tool server connections via AIOHTTP client. +#### `REQUESTS_VERIFY` + +- Type: `bool` +- Default: `True` +- Description: Controls SSL/TLS verification for synchronous `requests` (e.g., Tika, External Reranker). Set to `False` to bypass certificate verification for self-signed certificates. + ### Directories #### `DATA_DIR` @@ -551,6 +564,18 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model- - Default: `INFO` - Description: Sets the global logging level for all Open WebUI components. Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. +#### `ENABLE_AUDIT_STDOUT` + +- Type: `bool` +- Default: `False` +- Description: Controls whether audit logs are output to stdout (console). Useful for containerized environments where logs are collected from stdout. + +#### `ENABLE_AUDIT_LOGS_FILE` + +- Type: `bool` +- Default: `True` +- Description: Controls whether audit logs are written to a file. When enabled, logs are written to the location specified by `AUDIT_LOGS_FILE_PATH`. + #### `AUDIT_LOGS_FILE_PATH` - Type: `str` @@ -2741,6 +2766,12 @@ If you are embedding externally via API, ensure your rate limits are high enough - Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION` + +- Type: `bool` +- Default: `True` +- Description: When enabled (default), applies sigmoid normalization to local CrossEncoder reranking scores to ensure they fall within the 0-1 range. This allows the relevance threshold setting to work correctly with models like MS MARCO that output raw logits. + #### `RAG_EXTERNAL_RERANKER_TIMEOUT` - Type: `str` @@ -3184,6 +3215,13 @@ Brave's free tier enforces a rate limit of 1 request per second. Open WebUI auto - Description: Sets the API key for Jina. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `JINA_API_BASE_URL` + +- Type: `str` +- Default: `https://s.jina.ai/` +- Description: Sets the Base URL for Jina Search API. Useful for specifying custom or regional endpoints (e.g., `https://eu-s-beta.jina.ai/`). +- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > Web Search > Jina API Base URL**. + #### `BING_SEARCH_V7_ENDPOINT` - Type: `str` @@ -3416,6 +3454,13 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for: - Description: Sets the API key for Firecrawl API. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `FIRECRAWL_TIMEOUT` + +- Type: `int` +- Default: `None` +- Description: Specifies the timeout in milliseconds for Firecrawl requests. If not set, the default Firecrawl timeout is used. +- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > Web Search > Firecrawl Timeout**. + #### `PLAYWRIGHT_TIMEOUT` - Type: `int` diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 5f8f0f677..3f05066df 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -231,6 +231,35 @@ Encountered an SSL error? It could be an issue with the Hugging Face server. Her docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main ``` +## πŸ” SSL Certificate Issues with Internal Tools + +If you are using external tools like Tika, Ollama (for embeddings), or an external reranker with self-signed certificates, you might encounter SSL verification errors. + +### Common Symptoms + +- Logs show `[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate` +- Tika document ingestion fails +- Embedding generation fails with SSL errors +- Reranking fails with SSL errors + +### Solution + +You can disable SSL verification for these internal tool connections using the following environment variables: + +1. **For synchronous requests (Tika, External Reranker):** + ```bash + REQUESTS_VERIFY=false + ``` + +2. **For asynchronous requests (Ollama Embeddings):** + ```bash + AIOHTTP_CLIENT_SESSION_SSL=false + ``` + +:::warning +Disabling SSL verification reduces security. Only do this if you trust the network and the services you are connecting to (e.g., functioning within a secure internal network). +::: + ## 🍏 Podman on MacOS Running on MacOS with Podman? Here’s how to ensure connectivity: @@ -255,17 +284,32 @@ If you are having trouble connecting to MCP tools (e.g. "Failed to connect to MC See the [MCP Feature Documentation](/features/mcp#troubleshooting) for detailed troubleshooting steps. -## πŸ” SSL/TLS Errors with Web Search (Proxy Issues) +## πŸ” SSL/TLS Errors with Web Search + +If you are encountering SSL errors while using the Web Search feature, they usually fall into two categories: Proxy configuration issues or Certificate verification issues. + +### Certificate Verification Issues + +If you are seeing SSL verification errors when Open WebUI tries to fetch content from websites (Web Loader): + +- **Symptom**: `[SSL: CERTIFICATE_VERIFY_FAILED]` when loading search results. +- **Solution**: You can disable SSL verification for the Web Loader (scraper) specifically. + ```bash + ENABLE_WEB_LOADER_SSL_VERIFICATION=false + ``` + > **Note**: This setting applies to the *fetching* of web pages. If you are having SSL issues with the Search Engine itself (e.g., local SearXNG) or subsequent steps (Embedding/Reranking), see the sections below. + +### Proxy Configuration Issues If you're seeing SSL errors like `UNEXPECTED_EOF_WHILE_READING` or `Max retries exceeded` when using web search providers (Bocha, Tavily, etc.): -### Common Symptoms +#### Common Symptoms - `SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING]'))` - `Max retries exceeded with url: /v1/web-search` - Web search works in standalone Python scripts but fails in Open WebUI -### Cause: HTTP Proxy Configured for HTTPS Traffic +#### Cause: HTTP Proxy Configured for HTTPS Traffic This typically happens when you have an **HTTP proxy** configured for **HTTPS traffic**. The HTTP proxy cannot properly handle TLS connections, causing SSL handshake failures. @@ -275,7 +319,7 @@ Check your environment for these variables: If your `https_proxy` points to `http://...` (HTTP) instead of `https://...` (HTTPS), SSL handshakes will fail because the proxy terminates the connection unexpectedly. -### Solutions +#### Solutions 1. **Fix proxy configuration**: Use an HTTPS-capable proxy for HTTPS traffic, or configure your HTTP proxy to properly support CONNECT tunneling for SSL 2. **Bypass proxy for specific hosts**: Set `NO_PROXY` environment variable: @@ -284,6 +328,6 @@ If your `https_proxy` points to `http://...` (HTTP) instead of `https://...` (HT ``` 3. **Disable proxy if not needed**: Unset the proxy environment variables entirely -### Why Standalone Scripts Work +#### Why Standalone Scripts Work When you run a Python script directly, it may not inherit the same proxy environment variables that your Open WebUI service is using. The service typically inherits environment variables from systemd, Docker, or your shell profile, which may have different proxy settings. diff --git a/docs/troubleshooting/rag.mdx b/docs/troubleshooting/rag.mdx index 09d17888e..c5229362e 100644 --- a/docs/troubleshooting/rag.mdx +++ b/docs/troubleshooting/rag.mdx @@ -133,9 +133,28 @@ If you're not sure whether the issue is with retrieval, token limits, or embeddi - GPT-4o handles larger inputs (128k tokens!) - Provides a great benchmark to evaluate your system's RAG reliability + +--- + +### 6. Upload Limits and Restrictions πŸ›‘ + +Open WebUI implements various limits to ensure system stability and prevent abuse. It is important to understand how these limits apply to different upload methods: + +* **Chat Uploads:** Subject to global file size and count limits. + * **Max File Size:** Controlled by `RAG_FILE_MAX_SIZE` (default: Unlimited). Configurable in **Admin Panel > Settings > Documents > General > Max Upload Size**. + * **Max File Count:** Controlled by `RAG_FILE_MAX_COUNT` (default: Unlimited). Configurable in **Admin Panel > Settings > Documents > General > Max Upload Count**. + * **Allowed File Extensions:** Controlled by `RAG_ALLOWED_FILE_EXTENSIONS` (default: All). Configurable in **Admin Panel > Settings > Documents > General > Allowed File Extensions**. +* **Folder Uploads:** Subject to the `FOLDER_MAX_FILE_COUNT` [environment variable](/getting-started/env-configuration/#folder_max_file_count) (defaults to 100). This limit applies to the number of files directly associated with a folder. +* **Knowledge Base Uploads:** + * **File Limit:** Subject to the same `RAG_FILE_MAX_SIZE` limit as chats, but **not** subject to the `RAG_FILE_MAX_COUNT` limit, allowing for unlimited file uploads. + * **RAG Enforcement:** All files uploaded to a Knowledge Base are automatically indexed. However, similar to chat uploads, Knowledge Bases can also be used in **Full Context Mode** (accessible in chat settings), which feeds the full document content to the model instead of using vector search retrieval. + +:::info +By separating these limits, administrators can better manage resource usage across different features. For example, you might want to allow larger uploads in a curated Knowledge Base while restricting the number of files in ad-hoc Folder uploads. +::: + --- -## Summary Checklist βœ… | Problem | Fix | |--------|------| @@ -143,6 +162,7 @@ If you're not sure whether the issue is with retrieval, token limits, or embeddi | 🧹 Only part of content used | Enable Full Context Mode or Bypass Embedding | | ⏱ Limited by 2048 token cap | Increase model context length (Admin Panel > Models > Settings > Advanced Parameters for Ollama) or use large-context LLM | | πŸ“‰ Inaccurate retrieval | Switch to a better embedding model, then reindex | +| ❌ Upload limits bypass | Use Folder uploads (with `FOLDER_MAX_FILE_COUNT`) but note that Knowledge Base limits are separate | | Still confused? | Test with GPT-4o and compare outputs | --- From f1376ef086588bb54c433f1a11b4138ad3bce3ee Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 1 Jan 2026 14:45:09 +0100 Subject: [PATCH 2/5] Update brave.md --- docs/features/web-search/brave.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/features/web-search/brave.md b/docs/features/web-search/brave.md index be38e57f4..6acf397db 100644 --- a/docs/features/web-search/brave.md +++ b/docs/features/web-search/brave.md @@ -59,3 +59,13 @@ This means that even if your connection is fast enough to send multiple sequenti :::tip If you are on Brave's paid tier with higher rate limits, you can increase `RAG_WEB_SEARCH_CONCURRENT_REQUESTS` for faster parallel searches. ::: + +:::info Understanding Concurrency & Rate Limits + +The `RAG_WEB_SEARCH_CONCURRENT_REQUESTS` setting controls concurrency **per individual search request**, not globally across the entire application. + +- **When this is NOT an issue**: For single-user instances or low-traffic setups where users rarely hit "Enter" at the exact same second, setting concurrency to `1` is usually sufficient to stay within the Free Tier limits (1 req/sec). +- **When this IS an issue**: If multiple users trigger web searches at the exact same moment (e.g., 3 users searching in the same second), Open WebUI will process these requests in parallel. Each user's request creates its own connection pool, meaning 3 requests will be sent to the API simultaneously, triggering a rate limit error on the Free Tier. + +**Note:** If you are running an environment with multiple concurrent users actively using web search, it is highly recommended to upgrade to a paid API tier. The Free Tier is not designed to support the throughput of a multi-user deployment. +::: From 88165d8ac5818b1fd27d89fbcc7b78ef441e748a Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 1 Jan 2026 15:36:09 +0100 Subject: [PATCH 3/5] image gen --- .../{gemini.md => gemini.mdx} | 38 +++++++++++++++---- docs/getting-started/env-configuration.mdx | 17 +-------- 2 files changed, 32 insertions(+), 23 deletions(-) rename docs/features/image-generation-and-editing/{gemini.md => gemini.mdx} (75%) diff --git a/docs/features/image-generation-and-editing/gemini.md b/docs/features/image-generation-and-editing/gemini.mdx similarity index 75% rename from docs/features/image-generation-and-editing/gemini.md rename to docs/features/image-generation-and-editing/gemini.mdx index 58764f794..7d007c206 100644 --- a/docs/features/image-generation-and-editing/gemini.md +++ b/docs/features/image-generation-and-editing/gemini.mdx @@ -31,12 +31,34 @@ Alternatively, if you are using Vertex AI, you can create an API key in Google C 5. Enter the model you wish to use from these [available models](https://ai.google.dev/gemini-api/docs/imagen#model-versions). 6. Set the image size to one of the available [image sizes](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios). +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ### Example Minimal Setup -One minimalistic working setup for Gemini can look like this: + + -#### Create Image +**Create Image** +- **Create Image Model**: `gemini-3-pro-image-preview` +- **Image Size**: `2816x1536` +- **Image Prompt Generation**: on +- **Image Generation Engine**: `Gemini` +- **Gemini Base URL**: `https://generativelanguage.googleapis.com/v1beta` +- **Gemini API Key**: Enter your API Key +- **Gemini Endpoint Method**: `generateContent` +**Edit Image** +- **Image Edit Engine**: `Gemini` +- **Model**: `gemini-3-pro-image-preview` +- **Image Size**: (can be left empty) +- **Gemini Base URL**: `https://generativelanguage.googleapis.com/v1beta` +- **Gemini API Key**: Enter your API Key + + + + +**Create Image** - **Create Image Model**: `gemini-2.5-flash-image` - **Image Size**: `2816x1536` - **Image Prompt Generation**: on @@ -45,14 +67,16 @@ One minimalistic working setup for Gemini can look like this: - **Gemini API Key**: Enter your API Key - **Gemini Endpoint Method**: `generateContent` -#### Edit Image - +**Edit Image** - **Image Edit Engine**: `Gemini` - **Model**: `gemini-2.5-flash-image` - **Image Size**: (can be left empty) - **Gemini Base URL**: `https://generativelanguage.googleapis.com/v1beta` - **Gemini API Key**: Enter your API Key + + + ![Screenshot of the Open WebUI Images settings page with Gemini selected and the API key, model, and image size fields highlighted.](/images/image-generation-and-editing/gemini-settings.png) :::info @@ -69,12 +93,12 @@ Imagen model endpoint example: Gemini model endpoint example: -- `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent`. +- `https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent`. - [Documentation for Gemini models](https://ai.google.dev/gemini-api/docs/image-generation) -Trying to call a Gemini model, such as gemini-2.5-flash-image aka *Nano Banana* would result in an error due to the difference in supported endpoints for Image Generation. +Trying to call a Gemini model, such as `gemini-3-pro-image-preview` would result in an error due to the difference in supported endpoints for Image Generation. -`400: [ERROR: models/gemini-2.5-flash-image is not found for API version v1beta, or is not supported for predict. Call ListModels to see the list of available models and their supported methods.]` +`400: [ERROR: models/gemini-3-pro-image-preview is not found for API version v1beta, or is not supported for predict. Call ListModels to see the list of available models and their supported methods.]` ::: diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 6e74c2145..181414879 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -3949,22 +3949,7 @@ Strictly return in JSON format: :::tip -One minimalistic working setup for Gemini can look like this: - -- Create Image - - Model: `gemini-2.5-flash-image` - - Image Size: `2816x1536` - - Image Prompt Generation: on - - Image Generation Engine: `Gemini` - - Gemini Base URL: `https://generativelanguage.googleapis.com/v1beta` - - Gemini API Key: Enter your API Key - - Gemini Endpoint Method: `generateContent` -- Edit Image - - Image Edit Engine: `Gemini` - - Model: `gemini-2.5-flash-image` - - Image Size: (can be left empty) - - Gemini Base URL: `https://generativelanguage.googleapis.com/v1beta` - - Gemini API Key: Enter your API Key +For a detailed setup guide and example configuration, please refer to the [Gemini Image Generation Guide](/features/image-generation-and-editing/gemini). ::: From 5736f546993dc8e6929a24b74762eb1e527d901f Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 1 Jan 2026 15:36:16 +0100 Subject: [PATCH 4/5] image gen --- .../image-generation-and-editing/usage.md | 22 ++++++ docs/features/index.mdx | 2 +- docs/troubleshooting/image-generation.md | 70 +++++++++++++++++++ 3 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 docs/troubleshooting/image-generation.md diff --git a/docs/features/image-generation-and-editing/usage.md b/docs/features/image-generation-and-editing/usage.md index 0861de5cd..9898a1a11 100644 --- a/docs/features/image-generation-and-editing/usage.md +++ b/docs/features/image-generation-and-editing/usage.md @@ -19,4 +19,26 @@ Before you can use image generation, you must ensure that the **Image Generation You can also edit the LLM's response and enter your image generation prompt as the message to send off for image generation instead of using the actual response provided by the LLM. + ::: + + +:::info +**Requirement:** To use **Image Editing** or **Image+Image Generation**, you must have an **Image Generation Model** configured in the Admin Settings that supports these features (e.g., OpenAI DALL-E, or a ComfyUI/Automatic1111 model with appropriate inpainting/img2img capabilities). +::: + +## Image Editing (Inpainting) + +You can edit an image by providing the image and a text prompt directly in the chat. + +1. **Upload an image** to the chat. +2. **Enter a prompt** describing the change you want to make (e.g., "Change the background to a sunset" or "Add a hat"). +3. The model will generate a new version of the image based on your prompt. + +## Image Compositing (Multi-Image Fusion) + +Seamlessly combine multiple images into a single cohesive sceneβ€”a process professionally known as **Image Compositing** or **Multi-Image Fusion**. This allows you to merge elements from different sources (e.g., placing a subject from one image into the background of another) while harmonizing lighting, perspective, and style. + +1. **Upload images** to the chat (e.g., upload an image of a subject and an image of a background). +2. **Enter a prompt** describing the desired composition (e.g., "Combine these images to show the cat sitting on the park bench, ensuring consistent lighting"). +3. The model will generate a new composite image that fuses the elements according to your instructions. diff --git a/docs/features/index.mdx b/docs/features/index.mdx index a24bf0561..c52c76aff 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -41,7 +41,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; - 🌐 **Web Browsing Capabilities**: Integrate websites seamlessly into your chat experience by using the `#` command followed by a URL. This feature enables the incorporation of web content directly into your conversations, thereby enhancing the richness and depth of your interactions. -- 🎨 **Image Generation & Editing Integration**: Seamlessly create and edit images using multiple engines including OpenAI's DALL-E (generation and editing), Gemini (generation and editing), ComfyUI (local, generation and editing), and AUTOMATIC1111 (local, generation). Support for both text-to-image generation and prompt-based image editing workflows with dynamic visual content. [Learn more about Image Gen](/category/create--edit-images). +- 🎨 **Image Generation & Editing Integration**: Seamlessly create and edit images using multiple engines including OpenAI's DALL-E, Gemini, ComfyUI, and AUTOMATIC1111. Open WebUI now supports **Image Compositing** and **Image Editing** (inpainting/editing), allowing you to transform existing images and refine your creations with ease. [Learn more about Image Gen](/category/create--edit-images). - βš™οΈ **Concurrent Model Utilization**: Effortlessly engage with multiple models simultaneously, harnessing their unique strengths for optimal responses. Leverage a diverse set of model modalities in parallel to enhance your experience. diff --git a/docs/troubleshooting/image-generation.md b/docs/troubleshooting/image-generation.md new file mode 100644 index 000000000..048d5dceb --- /dev/null +++ b/docs/troubleshooting/image-generation.md @@ -0,0 +1,70 @@ +--- +sidebar_position: 100 +title: "Image Generation" +--- + +## 🎨 Image Generation Troubleshooting + +### General Issues + +- **Image Not Generating**: + - Check the **Images** settings in the **Admin Panel** > **Settings** > **Images**. Ensure "Image Generation" is toggled **ON**. + - Verify your **API Key** and **Base URL** (for OpenAI, ComfyUI, Automatic1111) are correct. + - Ensure the selected model is available and loaded in your backend service (e.g., check the ComfyUI or Automatic1111 console for activity). + +### ComfyUI Issues + +- **Incompatible Workflow / JSON Errors**: + - **API Format Required**: Open WebUI requires workflows to be in the **API Format**. + - In ComfyUI: + 1. Click the "Settings" (gear icon). + 2. Enable "Enable Dev mode Options". + 3. Click "Save (API Format)" in the menu. + - **Do not** use the standard "Save" button or standard JSON export. + +- **Image Editing / Image Variation Fails**: + - If you are using Image Editing or Image+Image generation, your custom workflow **must** have nodes configured to accept an input image (usually a `LoadImage` node replaced/linked effectively). + - Check the default "Image Editing" workflow in the Open WebUI settings for the required node structure to ensure compatibility. + +### Automatic1111 Issues + +- **Connection Refused / "Api Not Found"**: + - Ensure you are running Automatic1111 with the `--api` flag enabled in your command line arguments. + +- **Docker Connectivity**: + - If Open WebUI is running in Docker and Automatic1111 is on your host machine: + - Use `http://host.docker.internal:7860` as the Base URL. + - Ensure `host.docker.internal` is resolvable (added via `--add-host=host.docker.internal:host-gateway` in your Docker run command). + +### Environment Variables & Configuration + +For advanced configuration, you can set the following environment variables. + +#### General Image Generation +- `ENABLE_IMAGE_GENERATION`: Set to `true` to enable image generation. +- `IMAGE_GENERATION_ENGINE`: The engine to use (e.g., `openai`, `comfyui`, `automatic1111`, `gemini`). +- `IMAGE_GENERATION_MODEL`: The model ID to use for generation. +- `IMAGE_SIZE`: Default image size (e.g., `512x512`). + +#### Engine Specifics + +**OpenAI / Compatible** +- `IMAGES_OPENAI_API_BASE_URL`: Base URL for OpenAI-compatible image generation API. +- `IMAGES_OPENAI_API_KEY`: API Key for the image generation service. + +**ComfyUI** +- `COMFYUI_BASE_URL`: Base URL for your ComfyUI instance. +- `COMFYUI_API_KEY`: API Key (if authentication is enabled). +- `COMFYUI_WORKFLOW`: Custom workflow JSON (must be API format). + +**Automatic1111** +- `AUTOMATIC1111_BASE_URL`: Base URL for your Automatic1111 instance. +- `AUTOMATIC1111_API_AUTH`: Authentication credentials (username:password). + +**Gemini** +- `IMAGES_GEMINI_API_KEY`: API Key for Gemini. +- [View Gemini Configuration Guide](/features/image-generation-and-editing/gemini) + +:::tip +For a complete list of environment variables and detailed configuration options, please refer to the [Environment Configuration Guide](/getting-started/env-configuration). +::: From 7f898d8cc543489fe4e54a7c5c717d762b38150d Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 1 Jan 2026 16:04:01 +0100 Subject: [PATCH 5/5] Update gemini.mdx --- docs/features/image-generation-and-editing/gemini.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/features/image-generation-and-editing/gemini.mdx b/docs/features/image-generation-and-editing/gemini.mdx index 7d007c206..ea954434a 100644 --- a/docs/features/image-generation-and-editing/gemini.mdx +++ b/docs/features/image-generation-and-editing/gemini.mdx @@ -11,15 +11,15 @@ Open WebUI also supports image generation through the **Google AI Studio API** a ### Initial Setup -1. Obtain an [API key](https://aistudio.google.com/api-keys) from Google AI Studio. -2. You may need to create a project and enable the `Generative Language API` in addition to adding billing information. +1. Obtain an [API key](https://aistudio.google.com/api-keys) from Google AI Studio - alternatively an API Key from Google Cloud and activate the `Generative Language API` for the project. +2. You most likely need to create a project and enable the `Generative Language API` in addition to adding billing information, because the image generation API is not available for free. :::warning If you are utilizing a free API key, it is vital to have a payment method on file. The absence of a valid payment method is a frequent cause of errors during the setup process. ::: :::tip -Alternatively, if you are using Vertex AI, you can create an API key in Google Cloud instead of a service account. This key will function correctly, provided it is assigned the appropriate permissions. +Alternatively, if you are using Vertex AI, you can create an API key in Google Cloud instead of a service account. This key will function correctly, provided it is assigned the appropriate permissions. And given the Generative Language API is enabled for the project. ::: ### Configuring Open WebUI @@ -55,7 +55,7 @@ import TabItem from '@theme/TabItem'; - **Gemini Base URL**: `https://generativelanguage.googleapis.com/v1beta` - **Gemini API Key**: Enter your API Key - + **Create Image** @@ -74,7 +74,7 @@ import TabItem from '@theme/TabItem'; - **Gemini Base URL**: `https://generativelanguage.googleapis.com/v1beta` - **Gemini API Key**: Enter your API Key - + ![Screenshot of the Open WebUI Images settings page with Gemini selected and the API key, model, and image size fields highlighted.](/images/image-generation-and-editing/gemini-settings.png)