feat: add OPENWEBUI_MODE for OpenWebUI tool integration

- Add OPENWEBUI_MODE config that returns ["data:mime;base64,..."] format
- OpenWebUI extracts this as a file and displays the image correctly
- Change default response_format from "markdown" to "url"
- Keep MARKDOWN_EMBED_IMAGES for backwards compatibility
- Update CONFIGURATION.md with response format reference table

Author: danielcopper

CONFIGURATION.md

@@ -46,7 +46,7 @@ Complete configuration reference for the Image Generation API.
 **`SAVE_IMAGES_LOCALLY`**
 - Save images to local disk
 - Default: `true`
-- Set to `false` when using `MARKDOWN_EMBED_IMAGES=true` with Open WebUI
+- Set to `false` when using `OPENWEBUI_MODE=true` or `MARKDOWN_EMBED_IMAGES=true`
 - When `false`, images are temporarily written for base64 conversion then deleted
 
 ### Model Defaults
@@ -58,12 +58,24 @@ Complete configuration reference for the Image Generation API.
 
 ### Response Configuration
 
+**`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 `false`:
+  - Normal API behavior based on `response_format` parameter
+- Requires: OpenWebUI with `ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION=true`
+
 **`MARKDOWN_EMBED_IMAGES`**
 - 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`
+- When `true` and `response_format="markdown"`: Returns `{"markdown": "![image](data:image/png;base64,...)"}`
+- When `false` and `response_format="markdown"`: Returns `{"markdown": "![image](http://...)"}`
+- Note: Ignored when `OPENWEBUI_MODE=true`
 
 ### Security
 
@@ -341,3 +353,13 @@ Use after LiteLLM configuration changes.
 - Verify `STORAGE_PATH` has write permissions
 - Check `BASE_URL` matches your deployment
 - For Docker, ensure volume is mounted correctly
+
+## 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,...)"}` |

app/api/routes/edit.py

@@ -165,19 +165,20 @@ async def edit_image(
 
 @router.post(
     "/json",
-    response_model=ImageResponse,
+    response_model=None,
     operation_id="edit_image_json",
     summary="Edit image (JSON)",
     description=(
         "Edit an existing image using a JSON request body. "
         "This endpoint is designed for LLM tool use - provide the image_url "
-        "from a previous generate_image response. Uses prompt-based editing."
+        "from a previous generate_image response. Uses prompt-based editing. "
+        "Response format depends on OPENWEBUI_MODE setting."
     ),
 )
 async def edit_image_json(
     request: ImageEditRequest,
     _: None = Depends(verify_token),
-) -> ImageResponse:
+):
     """
     Edit an image using JSON request body (LLM-friendly endpoint).
     """
@@ -218,7 +219,29 @@ async def edit_image_json(
     if not urls:
         raise HTTPException(status_code=500, detail="No images generated")
 
-    # Return markdown format (same as generate endpoint)
+    # OpenWebUI mode: return list with data URI for tool integration
+    if settings.OPENWEBUI_MODE:
+        image_filename = urls[0].split("/")[-1]
+        image_path = Path(settings.STORAGE_PATH) / image_filename
+
+        if not image_path.exists():
+            raise HTTPException(status_code=500, detail="Edited image file not found")
+
+        with open(image_path, "rb") as f:
+            image_data = base64.b64encode(f.read()).decode("utf-8")
+
+        # Clean up local file if not saving locally
+        if not settings.SAVE_IMAGES_LOCALLY:
+            with contextlib.suppress(Exception):
+                image_path.unlink()
+
+        ext = image_path.suffix.lower()
+        mime_types = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
+        mime_type = mime_types.get(ext, "image/png")
+
+        return [f"data:{mime_type};base64,{image_data}"]
+
+    # Return based on MARKDOWN_EMBED_IMAGES setting
     if settings.MARKDOWN_EMBED_IMAGES:
         # Return markdown with embedded base64 data URI
         image_filename = urls[0].split("/")[-1]

app/api/routes/generate.py

@@ -23,16 +23,17 @@
 
 @router.post(
     "",
-    response_model=ImageResponse,
+    response_model=None,
     operation_id="generate_image",
     summary="Generate image",
     description=(
         "Generate an image from a text prompt. "
         "Uses LiteLLM proxy by default for cost tracking, with fallback to direct API calls. "
-        "Supports OpenAI DALL-E and Google Gemini models."
+        "Supports OpenAI DALL-E and Google Gemini models. "
+        "Response format depends on OPENWEBUI_MODE and response_format parameter."
     ),
 )
-async def generate_image(request: ImageRequest, _: None = Depends(verify_token)) -> ImageResponse:
+async def generate_image(request: ImageRequest, _: None = Depends(verify_token)):
     """
     Generate image with standard JSON response.
     """
@@ -69,6 +70,28 @@ 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 list with data URI for tool integration
+    if settings.OPENWEBUI_MODE:
+        image_filename = urls[0].split("/")[-1]
+        image_path = Path(settings.STORAGE_PATH) / image_filename
+
+        if not image_path.exists():
+            raise HTTPException(status_code=500, detail="Generated image file not found")
+
+        with open(image_path, "rb") as f:
+            image_data = base64.b64encode(f.read()).decode("utf-8")
+
+        # Clean up local file if not saving locally
+        if not settings.SAVE_IMAGES_LOCALLY:
+            with contextlib.suppress(Exception):
+                image_path.unlink()
+
+        ext = image_path.suffix.lower()
+        mime_types = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
+        mime_type = mime_types.get(ext, "image/png")
+
+        return [f"data:{mime_type};base64,{image_data}"]
+
     # Handle response format
     if request.response_format == "base64":
         # Extract filename from URL and read file

app/core/config.py

@@ -43,9 +43,10 @@ class Settings(BaseSettings):
     # Storage Configuration
     STORAGE_PATH: str = "./generated_images"
     IMAGE_BASE_URL: str = "http://localhost:8000"  # URL where this API serves images
-    SAVE_IMAGES_LOCALLY: bool = True  # Set to false when using MARKDOWN_EMBED_IMAGES with Open WebUI
+    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
     MARKDOWN_EMBED_IMAGES: bool = False  # Embed images as base64 data URI in markdown responses
 
     # Security (Optional)

app/schemas/requests.py

@@ -55,12 +55,13 @@ class ImageRequest(BaseModel):
     )
 
     response_format: Literal["url", "base64", "markdown"] = Field(
-        default="markdown",
+        default="url",
         description=(
             "Response format for generated images. "
-            "'markdown': Returns markdown with image (default, best for LLM/chat integrations). "
-            "'url': Returns image URL only. "
-            "'base64': Returns base64 encoded data in JSON."
+            "'url': Returns image URL (default). "
+            "'base64': Returns base64 encoded data in JSON. "
+            "'markdown': Returns markdown with image. "
+            "Note: Ignored when OPENWEBUI_MODE=true."
         ),
     )