feat: add JSON-based edit endpoint for LLM tool use

The existing /edit endpoint uses multipart form-data which LLMs cannot
use as a tool. This adds /edit/json that accepts a JSON body with
image_url, prompt, provider, model, and n parameters.

Also adds authentication headers when fetching images from Open WebUI
URLs to ensure edited images can be retrieved.

Author: danielcopper

app/api/routes/edit.py

@@ -7,6 +7,7 @@
 
 from app.core.config import settings
 from app.core.security import verify_token
+from app.schemas.requests import ImageEditRequest
 from app.schemas.responses import ImageResponse
 from app.services.gemini_service import get_gemini_service
 from app.services.litellm_service import get_litellm_service
@@ -161,6 +162,75 @@ async def edit_image(
     )
 
 
+@router.post(
+    "/json",
+    response_model=ImageResponse,
+    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."
+    ),
+)
+async def edit_image_json(
+    request: ImageEditRequest,
+    _: None = Depends(verify_token),
+) -> ImageResponse:
+    """
+    Edit an image using JSON request body (LLM-friendly endpoint).
+    """
+    logger.info(f"Edit JSON request: provider={request.provider}, model={request.model}")
+
+    # Load image from URL
+    try:
+        image_bytes = await storage_service.get_image(request.image_url)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+    except Exception as e:
+        logger.error(f"Failed to load image: {e}")
+        raise HTTPException(status_code=400, detail=f"Failed to load image: {str(e)}") from None
+
+    # Determine model if not specified
+    model = request.model
+    if not model:
+        model = _get_default_edit_model(request.provider)
+
+    # Get service based on provider
+    try:
+        service = _get_service(request.provider)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from None
+
+    # Edit image (prompt-based, no mask for JSON endpoint)
+    try:
+        urls = await service.edit_image(
+            image=image_bytes,
+            prompt=request.prompt,
+            model=model,
+            n=request.n,
+        )
+    except Exception as e:
+        logger.error(f"Edit failed: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Edit failed: {str(e)}") from None
+
+    if not urls:
+        raise HTTPException(status_code=500, detail="No images generated")
+
+    return ImageResponse(
+        image_url=urls[0],
+        prompt=request.prompt,
+        model=model,
+        provider=request.provider,
+        metadata={
+            "all_urls": urls if len(urls) > 1 else None,
+            "n": len(urls),
+            "edit": True,
+            "source_image": request.image_url,
+        },
+    )
+
+
 def _get_service(provider: str):
     """Get service instance based on provider."""
     if provider == "litellm":

app/schemas/requests.py

@@ -67,6 +67,43 @@ class ImageRequest(BaseModel):
     stream: bool = Field(default=False, description="Enable SSE streaming for progress updates")
 
 
+class ImageEditRequest(BaseModel):
+    """
+    Request schema for image editing (JSON endpoint for LLM tool use).
+    """
+
+    image_url: str = Field(
+        ...,
+        description="URL to the image to edit. Use the image_url from a previous generate_image response.",
+        examples=["https://chat.example.com/api/v1/files/abc123/content"],
+    )
+
+    prompt: str = Field(
+        ...,
+        description="Description of the edit to make. Be specific about what should change.",
+        min_length=1,
+        max_length=4000,
+        examples=["Make the sky more dramatic with orange sunset colors"],
+    )
+
+    provider: Literal["litellm", "gemini"] = Field(
+        default="litellm",
+        description="Provider for editing. Use 'litellm' (default) or 'gemini' for prompt-based editing.",
+    )
+
+    model: str | None = Field(
+        default=None,
+        description="Model ID for editing. Server uses default if not specified.",
+    )
+
+    n: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of variations to generate",
+    )
+
+
 class ModelRefreshRequest(BaseModel):
     """
     Request schema for refreshing model registry.

app/services/storage_service.py

@@ -84,8 +84,16 @@ async def get_image(self, url: str) -> bytes:
                 return await f.read()
 
         # External URL - fetch via HTTP
+        headers = {}
+
+        # Add authentication for Open WebUI URLs
+        if settings.openwebui_available and settings.OPENWEBUI_BASE_URL:
+            openwebui_base = settings.OPENWEBUI_BASE_URL.rstrip("/")
+            if url.startswith(openwebui_base):
+                headers["Authorization"] = f"Bearer {settings.OPENWEBUI_API_KEY}"
+
         async with httpx.AsyncClient(timeout=30.0) as client:
-            response = await client.get(url)
+            response = await client.get(url, headers=headers)
             response.raise_for_status()
             return response.content
 

tests/test_edit.py

@@ -110,6 +110,8 @@ async def test_storage_get_image_external():
     with patch("app.services.storage_service.settings") as mock_settings:
         mock_settings.STORAGE_PATH = "/tmp/test"
         mock_settings.IMAGE_BASE_URL = "http://localhost:8000"
+        mock_settings.openwebui_available = False
+        mock_settings.OPENWEBUI_BASE_URL = None
 
         service = StorageService()
 
@@ -127,7 +129,7 @@ async def test_storage_get_image_external():
             result = await service.get_image("https://example.com/image.png")
 
             assert result == b"external image data"
-            mock_client.get.assert_called_once_with("https://example.com/image.png")
+            mock_client.get.assert_called_once_with("https://example.com/image.png", headers={})
 
 
 def test_get_default_edit_model():