feat(owui): add native image display via OWUI file upload

Upload images directly to Open WebUI's file storage (/api/v1/files/)
when OPENWEBUI_BASE_URL and OPENWEBUI_API_KEY are configured. Images
display natively in chat with download/save, replacing the base64
HTMLResponse iframe workaround. Falls back gracefully to the existing
approach when OWUI upload is not configured or fails.

Author: danielcopper

.env.example

@@ -38,13 +38,25 @@ IMAGE_BASE_URL=http://localhost:8000
 # (images will be stored by Open WebUI instead)
 SAVE_IMAGES_LOCALLY=true
 
+# -----------------------------------------------------------------------------
+# Open WebUI Integration
+# -----------------------------------------------------------------------------
+# Enable Open WebUI tool integration mode (default: false)
+OPENWEBUI_MODE=false
+
+# Open WebUI server URL for native image display (uploads images to OWUI file storage)
+# Example: http://open-webui:3000 or http://localhost:3000
+OPENWEBUI_BASE_URL=
+
+# Open WebUI API key (generate in OWUI: Settings > Account > API Keys)
+OPENWEBUI_API_KEY=
+
 # -----------------------------------------------------------------------------
 # Response Configuration
 # -----------------------------------------------------------------------------
 # Embed images as base64 data URI in markdown responses (default: false)
 # When true: Returns ![image](data:image/png;base64,...)
 # When false: Returns ![image](http://...)
-# Set to true for Open WebUI integration with ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION
 MARKDOWN_EMBED_IMAGES=false
 
 # -----------------------------------------------------------------------------

CONFIGURATION.md

@@ -61,14 +61,29 @@ Complete configuration reference for the Image Generation API.
 **`OPENWEBUI_MODE`**
 - Enable Open WebUI tool integration mode
 - Default: `false`
-- When `true`:
-  - Returns `["data:image/png;base64,..."]` (list with data URI)
-  - OpenWebUI extracts this as a file and displays the image
-  - Overrides `response_format` parameter and `MARKDOWN_EMBED_IMAGES`
-  - Works with OpenWebUI's tool response handling
+- When `true` and `OPENWEBUI_BASE_URL` + `OPENWEBUI_API_KEY` are set:
+  - Uploads images to Open WebUI's file storage via `/api/v1/files/`
+  - Returns JSON with the OWUI file URL and markdown
+  - Images display natively in Open WebUI (with download/save)
+  - Falls back to base64 HTMLResponse if upload fails
+- When `true` without OWUI upload configured:
+  - Returns HTML with base64-encoded `<img>` tag (legacy iframe mode)
 - When `false`:
   - Normal API behavior based on `response_format` parameter
-- Requires: OpenWebUI with `ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION=true`
+
+### Open WebUI Integration
+
+**`OPENWEBUI_BASE_URL`**
+- Open WebUI server URL for file upload integration
+- Example: `http://open-webui:3000` or `http://localhost:3000`
+- Optional - leave empty to use legacy base64 HTMLResponse mode
+- Used with `OPENWEBUI_MODE=true` to upload images directly to OWUI
+
+**`OPENWEBUI_API_KEY`**
+- API key for Open WebUI authentication
+- Required when `OPENWEBUI_BASE_URL` is set
+- Generate in Open WebUI: Settings > Account > API Keys
+- Used for `POST /api/v1/files/` uploads
 
 **`MARKDOWN_EMBED_IMAGES`**
 - Embed images as base64 data URI in markdown responses
@@ -386,10 +401,11 @@ Use after LiteLLM configuration changes.
 
 ## Response Format Reference
 
-| `OPENWEBUI_MODE` | `MARKDOWN_EMBED_IMAGES` | `response_format` | Response |
-|------------------|-------------------------|-------------------|----------|
-| `true` | (ignored) | (ignored) | `["data:image/png;base64,..."]` |
-| `false` | `false` | `url` (default) | `{"image_url": "http://..."}` |
-| `false` | `false` | `base64` | `{"image_base64": "...", "mime_type": "..."}` |
-| `false` | `false` | `markdown` | `{"markdown": "![img](http://...)"}` |
-| `false` | `true` | `markdown` | `{"markdown": "![img](data:...;base64,...)"}` |
+| `OPENWEBUI_MODE` | OWUI Upload | `MARKDOWN_EMBED_IMAGES` | `response_format` | Response |
+|------------------|-------------|-------------------------|-------------------|----------|
+| `true` | configured | (ignored) | (ignored) | `{"image_url": "http://owui/api/v1/files/.../content", "markdown": "![img](...)"}` |
+| `true` | not configured | (ignored) | (ignored) | HTML `<img>` with base64 data URI (iframe) |
+| `false` | — | `false` | `url` (default) | `{"image_url": "http://..."}` |
+| `false` | — | `false` | `base64` | `{"image_base64": "...", "mime_type": "..."}` |
+| `false` | — | `false` | `markdown` | `{"markdown": "![img](http://...)"}` |
+| `false` | — | `true` | `markdown` | `{"markdown": "![img](data:...;base64,...)"}` |

README.md

@@ -171,6 +171,23 @@ See [CONFIGURATION.md](CONFIGURATION.md) for details.
 
 For admin/global tools, configure in Admin Settings with server-accessible URL.
 
+### Native Image Display (Recommended)
+
+For the best experience (images display natively in chat with download/save):
+
+1. Generate an API key in Open WebUI: **Settings > Account > API Keys**
+2. Configure in `.env`:
+
+```env
+OPENWEBUI_MODE=true
+OPENWEBUI_BASE_URL=http://open-webui:3000
+OPENWEBUI_API_KEY=your-owui-api-key
+```
+
+Images are uploaded directly to Open WebUI's file storage and displayed inline, just like the built-in image generation.
+
+Without `OPENWEBUI_BASE_URL`/`OPENWEBUI_API_KEY`, falls back to base64 HTMLResponse (iframe display).
+
 ## API Endpoints
 
 ### Image Generation

TODO.md

@@ -25,12 +25,10 @@ Add models released since the last update:
 - Test with LiteLLM model discovery
 
 ## 3. Improve OWUI Image Display
-Status: PENDING
+Status: DONE
 
-Current approach returns HTMLResponse with base64-encoded `<img>` tag — a workaround
-that went through several iterations. OWUI has had updates since; investigate:
-- Check current OWUI tool response handling (artifact display, image rendering)
-- See if OWUI now natively supports image URLs or base64 in tool responses without HTML hack
-- Consider using OWUI's file upload API to store images there directly
-- Reduce unnecessary disk I/O (currently writes to disk then reads back for base64)
-- Test with latest OWUI version and document the recommended setup
+Added Open WebUI file upload integration:
+- Images uploaded directly to OWUI via `POST /api/v1/files/` when `OPENWEBUI_BASE_URL` + `OPENWEBUI_API_KEY` configured
+- Returns JSON with OWUI file URL — images display natively in chat (with download/save)
+- Graceful fallback to base64 HTMLResponse when OWUI upload not configured or fails
+- Eliminated dependency on `ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION` setting

app/api/routes/edit.py

@@ -207,8 +207,24 @@ async def edit_image_json(
     if not urls:
         raise HTTPException(status_code=500, detail="No images generated")
 
-    # OpenWebUI mode: return HTML with embedded image for iframe display
+    # OpenWebUI mode
     if settings.OPENWEBUI_MODE:
+        if settings.openwebui_upload_available:
+            # OWUI upload succeeded — URL is already an OWUI file URL.
+            return ImageResponse(
+                image_url=urls[0],
+                markdown=f"![Edited image]({urls[0]})",
+                prompt=request.prompt,
+                model=model,
+                provider=request.provider,
+                metadata={
+                    "n": len(urls),
+                    "edit": True,
+                    "source_image": request.image_url,
+                    "all_urls": urls if len(urls) > 1 else None,
+                },
+            )
+        # Fallback: HTMLResponse with base64 (iframe display)
         try:
             image_data, mime_type = await read_image_as_base64(urls[0])
         except FileNotFoundError:

app/api/routes/generate.py

@@ -66,8 +66,25 @@ async def generate_image(request: ImageRequest, _: None = Depends(verify_token))
     if not urls:
         raise HTTPException(status_code=500, detail="No images generated")
 
-    # OpenWebUI mode: return HTML with embedded image for iframe display
+    # OpenWebUI mode
     if settings.OPENWEBUI_MODE:
+        if settings.openwebui_upload_available:
+            # OWUI upload succeeded — URL is already an OWUI file URL.
+            # Return ImageResponse so the LLM can include the URL in its message.
+            return ImageResponse(
+                image_url=urls[0],
+                markdown=f"![Generated image]({urls[0]})",
+                prompt=request.prompt,
+                model=model,
+                provider=request.provider,
+                metadata={
+                    "aspect_ratio": request.aspect_ratio,
+                    "quality": request.quality,
+                    "n": len(urls),
+                    "all_urls": urls if len(urls) > 1 else None,
+                },
+            )
+        # Fallback: HTMLResponse with base64 (iframe display)
         try:
             image_data, mime_type = await read_image_as_base64(urls[0])
         except FileNotFoundError:

app/core/config.py

@@ -46,9 +46,13 @@ class Settings(BaseSettings):
     SAVE_IMAGES_LOCALLY: bool = True  # Set to false when using OPENWEBUI_MODE or MARKDOWN_EMBED_IMAGES
 
     # Response Configuration
-    OPENWEBUI_MODE: bool = False  # Return ["data:mime;base64,..."] for OpenWebUI tool integration
+    OPENWEBUI_MODE: bool = False  # Enable OpenWebUI tool integration mode
     MARKDOWN_EMBED_IMAGES: bool = False  # Embed images as base64 data URI in markdown responses
 
+    # Open WebUI Integration
+    OPENWEBUI_BASE_URL: str | None = None  # e.g. http://open-webui:3000
+    OPENWEBUI_API_KEY: str | None = None  # API key for OWUI file upload
+
     # Security (Optional)
     API_BEARER_TOKEN: str | None = None
 
@@ -79,5 +83,10 @@ def gemini_available(self) -> bool:
         """Check if Gemini direct access is available."""
         return bool(self.GEMINI_API_KEY)
 
+    @property
+    def openwebui_upload_available(self) -> bool:
+        """Check if Open WebUI file upload is configured."""
+        return bool(self.OPENWEBUI_BASE_URL and self.OPENWEBUI_API_KEY)
+
 
 settings = Settings()

app/services/storage_service.py

@@ -15,7 +15,7 @@
 
 class StorageService:
     """
-    Handles local file storage for generated images.
+    Handles image storage — local filesystem and Open WebUI file upload.
     """
 
     def __init__(self):
@@ -24,15 +24,35 @@ def __init__(self):
 
     async def save_image(self, image_data: bytes, extension: str = "png") -> str:
         """
-        Save image bytes to local storage.
+        Save image bytes to the best available storage.
+
+        When OPENWEBUI_MODE is enabled and OWUI upload is configured, uploads
+        to Open WebUI's file storage and returns an OWUI file URL. Falls back
+        to local storage on failure or when OWUI upload is not configured.
 
         Args:
             image_data: Raw image bytes
             extension: File extension (png, jpg, webp)
 
         Returns:
-            Public URL to access the image
+            Public URL to access the image (OWUI URL or local URL)
         """
+        # Try OWUI upload when in OWUI mode with upload configured
+        if settings.OPENWEBUI_MODE and settings.openwebui_upload_available:
+            try:
+                owui_url = await self._upload_to_openwebui(image_data, extension)
+                # Also save locally if configured
+                if settings.SAVE_IMAGES_LOCALLY:
+                    await self._save_locally(image_data, extension)
+                return owui_url
+            except Exception as e:
+                logger.warning(f"OWUI upload failed, falling back to local storage: {e}")
+
+        # Local storage
+        return await self._save_locally(image_data, extension)
+
+    async def _save_locally(self, image_data: bytes, extension: str = "png") -> str:
+        """Save image bytes to local filesystem."""
         filename = f"{uuid.uuid4()}.{extension}"
         filepath = self.storage_path / filename
 
@@ -41,6 +61,28 @@ async def save_image(self, image_data: bytes, extension: str = "png") -> str:
 
         return f"{settings.IMAGE_BASE_URL.rstrip('/')}/images/{filename}"
 
+    async def _upload_to_openwebui(self, image_data: bytes, extension: str = "png") -> str:
+        """
+        Upload image to Open WebUI's file storage.
+
+        Returns:
+            OWUI file URL (e.g. http://open-webui:3000/api/v1/files/{id}/content)
+        """
+        filename = f"{uuid.uuid4()}.{extension}"
+        mime_type = f"image/{extension}"
+        base_url = settings.OPENWEBUI_BASE_URL.rstrip("/")
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(
+                f"{base_url}/api/v1/files/",
+                files={"file": (filename, image_data, mime_type)},
+                headers={"Authorization": f"Bearer {settings.OPENWEBUI_API_KEY}"},
+            )
+            response.raise_for_status()
+            file_id = response.json()["id"]
+            logger.info(f"Uploaded image to OWUI: {file_id}")
+            return f"{base_url}/api/v1/files/{file_id}/content"
+
     async def get_image(self, url: str) -> bytes:
         """
         Retrieve image bytes from URL or local storage.

tests/test_edit.py

@@ -59,6 +59,7 @@ async def test_storage_get_image_local(temp_storage):
     with patch("app.services.storage_service.settings") as mock_settings:
         mock_settings.STORAGE_PATH = str(temp_storage)
         mock_settings.IMAGE_BASE_URL = "http://localhost:8000"
+        mock_settings.OPENWEBUI_MODE = False
 
         service = StorageService()
 
@@ -79,6 +80,7 @@ async def test_storage_get_image_local_relative(temp_storage):
     with patch("app.services.storage_service.settings") as mock_settings:
         mock_settings.STORAGE_PATH = str(temp_storage)
         mock_settings.IMAGE_BASE_URL = "http://localhost:8000"
+        mock_settings.OPENWEBUI_MODE = False
 
         service = StorageService()