feat: add markdown response format for chat/LLM integrations

Author: danielcopper

.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: Release
 
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v*'
 
 permissions:
   contents: read
@@ -16,7 +17,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.release.tag_name }}
+          ref: ${{ github.ref }}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3

app/api/routes/generate.py

@@ -1,7 +1,6 @@
 import base64
 import logging
 from pathlib import Path
-from typing import List
 
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import HTMLResponse, StreamingResponse
@@ -99,6 +98,22 @@ async def generate_image(request: ImageRequest, _: None = Depends(verify_token))
             },
         )
 
+    if request.response_format == "markdown":
+        # Return ready-to-use markdown with image URL
+        markdown = f"![Generated image]({urls[0]})"
+        return ImageResponse(
+            markdown=markdown,
+            image_url=urls[0],
+            prompt=request.prompt,
+            model=model,
+            provider=request.provider,
+            metadata={
+                "aspect_ratio": request.aspect_ratio,
+                "quality": request.quality,
+                "n": len(urls),
+            },
+        )
+
     return ImageResponse(
         image_url=urls[0],
         prompt=request.prompt,

app/core/config.py

@@ -1,6 +1,5 @@
 import tomllib
 from pathlib import Path
-from typing import Optional
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -34,19 +33,19 @@ class Settings(BaseSettings):
     )
 
     # LiteLLM Configuration (Primary)
-    LITELLM_BASE_URL: Optional[str] = None
-    LITELLM_API_KEY: Optional[str] = None
+    LITELLM_BASE_URL: str | None = None
+    LITELLM_API_KEY: str | None = None
 
     # Direct Provider API Keys (Fallback)
-    OPENAI_API_KEY: Optional[str] = None
-    GEMINI_API_KEY: Optional[str] = None
+    OPENAI_API_KEY: str | None = None
+    GEMINI_API_KEY: str | None = None
 
     # Storage Configuration
     STORAGE_PATH: str = "./generated_images"
     BASE_URL: str = "http://localhost:8000"
 
     # Security (Optional)
-    API_BEARER_TOKEN: Optional[str] = None
+    API_BEARER_TOKEN: str | None = None
 
     # Model Registry
     MODEL_CACHE_TTL: int = 3600  # Cache models for 1 hour

app/core/security.py

@@ -1,4 +1,3 @@
-from typing import Optional
 
 from fastapi import HTTPException, Security, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
@@ -9,7 +8,7 @@
 
 
 async def verify_token(
-    credentials: Optional[HTTPAuthorizationCredentials] = Security(security),
+    credentials: HTTPAuthorizationCredentials | None = Security(security),
 ) -> None:
     """
     Verify Bearer token if configured.

app/schemas/requests.py

@@ -1,4 +1,4 @@
-from typing import Literal, Optional
+from typing import Literal
 
 from pydantic import BaseModel, Field
 
@@ -24,7 +24,7 @@ class ImageRequest(BaseModel):
         ),
     )
 
-    model: Optional[str] = Field(
+    model: str | None = Field(
         default=None,
         description=(
             "Model ID for image generation. Call GET /models to see all available models. "
@@ -54,12 +54,13 @@ class ImageRequest(BaseModel):
         description="Number of images to generate (1-4). Some models only support n=1",
     )
 
-    response_format: Literal["url", "base64"] = Field(
+    response_format: Literal["url", "base64", "markdown"] = Field(
         default="url",
         description=(
             "Response format for generated images. "
-            "Use 'base64' for chat integrations (returns image data directly, can be displayed inline). "
-            "Use 'url' only for web applications that can fetch external URLs."
+            "'url': Returns image URL (for web apps). "
+            "'base64': Returns base64 encoded data (for offline/serverless). "
+            "'markdown': Returns ready-to-use markdown with image URL (for chat/LLM integrations)."
         ),
     )
 

app/schemas/responses.py

@@ -1,32 +1,37 @@
-from typing import Any, Dict, List, Optional
+from typing import Any
 
-from pydantic import BaseModel, Field, HttpUrl
+from pydantic import BaseModel, Field
 
 
 class ImageResponse(BaseModel):
     """
     Response schema for image generation.
     """
 
-    image_url: Optional[str] = Field(
+    image_url: str | None = Field(
         default=None, description="URL to access the generated image (when response_format='url')"
     )
 
-    image_base64: Optional[str] = Field(
+    image_base64: str | None = Field(
         default=None, description="Base64 encoded image data (when response_format='base64')"
     )
 
-    mime_type: Optional[str] = Field(
+    mime_type: str | None = Field(
         default=None, description="MIME type of the image (e.g., 'image/png')"
     )
 
+    markdown: str | None = Field(
+        default=None,
+        description="Ready-to-use markdown with image URL (when response_format='markdown')",
+    )
+
     prompt: str = Field(..., description="The prompt used for generation")
 
     model: str = Field(..., description="The model that generated the image")
 
     provider: str = Field(..., description="The provider used (litellm, openai, gemini)")
 
-    metadata: Dict[str, Any] = Field(
+    metadata: dict[str, Any] = Field(
         default_factory=dict, description="Additional metadata about the generation"
     )
 
@@ -40,7 +45,7 @@ class ModelCapabilities(BaseModel):
         default=False, description="Whether model supports quality parameter"
     )
 
-    supports_aspect_ratios: List[str] = Field(
+    supports_aspect_ratios: list[str] = Field(
         default_factory=lambda: ["1:1"], description="Supported aspect ratios"
     )
 
@@ -66,11 +71,11 @@ class ModelListResponse(BaseModel):
     Response schema for listing available models.
     """
 
-    models: List[ModelInfo] = Field(..., description="List of available models")
+    models: list[ModelInfo] = Field(..., description="List of available models")
 
     cached: bool = Field(..., description="Whether results are from cache")
 
-    cache_expires_in: Optional[int] = Field(
+    cache_expires_in: int | None = Field(
         default=None, description="Seconds until cache expiration"
     )
 

app/services/gemini_service.py

@@ -1,5 +1,4 @@
 import logging
-from typing import List
 
 from google import genai
 from google.genai import types
@@ -36,7 +35,7 @@ async def generate_image(
         aspect_ratio: str = "1:1",
         quality: str = "standard",  # Not used for Gemini
         n: int = 1,
-    ) -> List[str]:
+    ) -> list[str]:
         """
         Generate images using Google Gemini API directly.
         """

app/services/litellm_service.py

@@ -1,6 +1,6 @@
 import base64
 import logging
-from typing import Any, Dict, List
+from typing import Any
 
 from openai import OpenAI
 
@@ -41,7 +41,7 @@ async def generate_image(
         aspect_ratio: str = "1:1",
         quality: str = "standard",
         n: int = 1,
-    ) -> List[str]:
+    ) -> list[str]:
         """
         Generate images using LiteLLM proxy.
 
@@ -62,7 +62,7 @@ async def generate_image(
         size = self._get_size(aspect_ratio)
 
         # Build request parameters
-        params: Dict[str, Any] = {
+        params: dict[str, Any] = {
             "model": model,
             "prompt": prompt,
             "n": n,

app/services/model_registry.py

@@ -1,6 +1,5 @@
 import logging
 import time
-from typing import Dict, List, Optional
 
 import httpx
 
@@ -17,7 +16,7 @@ class ModelRegistry:
     """
 
     # Model capabilities database (fallback for known models)
-    KNOWN_CAPABILITIES: Dict[str, ModelCapabilities] = {
+    KNOWN_CAPABILITIES: dict[str, ModelCapabilities] = {
         "dall-e-2": ModelCapabilities(
             supports_quality=False, supports_aspect_ratios=["1:1"], max_images=4
         ),
@@ -40,8 +39,8 @@ class ModelRegistry:
     }
 
     def __init__(self):
-        self._models: List[ModelInfo] = []
-        self._cache_timestamp: Optional[float] = None
+        self._models: list[ModelInfo] = []
+        self._cache_timestamp: float | None = None
 
     @property
     def cache_valid(self) -> bool:
@@ -52,14 +51,14 @@ def cache_valid(self) -> bool:
         return age < settings.MODEL_CACHE_TTL
 
     @property
-    def cache_age(self) -> Optional[int]:
+    def cache_age(self) -> int | None:
         """Get cache age in seconds."""
         if not self._cache_timestamp:
             return None
         return int(time.time() - self._cache_timestamp)
 
     @property
-    def cache_expires_in(self) -> Optional[int]:
+    def cache_expires_in(self) -> int | None:
         """Get seconds until cache expiration."""
         if not self._cache_timestamp:
             return None
@@ -69,7 +68,7 @@ def cache_expires_in(self) -> Optional[int]:
         remaining = settings.MODEL_CACHE_TTL - age
         return max(0, remaining)
 
-    async def load_models(self, force: bool = False) -> List[ModelInfo]:
+    async def load_models(self, force: bool = False) -> list[ModelInfo]:
         """
         Load available models from LiteLLM or fallback to static list.
 
@@ -104,7 +103,7 @@ async def load_models(self, force: bool = False) -> List[ModelInfo]:
 
         return self._models
 
-    async def _load_from_litellm(self) -> List[ModelInfo]:
+    async def _load_from_litellm(self) -> list[ModelInfo]:
         """
         Load models from LiteLLM /v1/models endpoint.
         """
@@ -135,7 +134,7 @@ async def _load_from_litellm(self) -> List[ModelInfo]:
 
         return models
 
-    def _get_static_models(self) -> List[ModelInfo]:
+    def _get_static_models(self) -> list[ModelInfo]:
         """
         Return static list of known models based on available API keys.
         """
@@ -201,13 +200,13 @@ def _get_capabilities(self, model_id: str) -> ModelCapabilities:
             max_images=4,
         )
 
-    def get_models(self) -> List[ModelInfo]:
+    def get_models(self) -> list[ModelInfo]:
         """
         Get cached models (non-async).
         """
         return self._models
 
-    def get_model(self, model_id: str) -> Optional[ModelInfo]:
+    def get_model(self, model_id: str) -> ModelInfo | None:
         """
         Get specific model info.
         """

app/services/openai_service.py

@@ -1,6 +1,6 @@
 import base64
 import logging
-from typing import Any, Dict, List
+from typing import Any
 
 from openai import OpenAI
 
@@ -53,7 +53,7 @@ async def generate_image(
         aspect_ratio: str = "1:1",
         quality: str = "standard",
         n: int = 1,
-    ) -> List[str]:
+    ) -> list[str]:
         """
         Generate images using OpenAI API directly.
         """
@@ -66,7 +66,7 @@ async def generate_image(
         model_info = model_registry.get_model(model)
 
         # Build request parameters
-        params: Dict[str, Any] = {
+        params: dict[str, Any] = {
             "model": model,
             "prompt": prompt,
             "n": n,