feat(chats): enhance message schema to support images (#652)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
  * Chats now support image attachments; message text is optional.
* Playground displays and saves images from both streaming and
non‑streaming replies.

* **Bug Fixes**
  * Copy-to-clipboard works even when a message has no text.

* **Documentation**
* API reference pages reformatted for readability (no behavioral
changes).
* Changelog updated with “Try it now in the Playground” links for the
Gemini 2.5 Flash Image Preview.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Luca Steeb <[email protected]>

Author: smakosh

apps/api/src/routes/chats.ts

@@ -22,7 +22,8 @@ const chatSchema = z.object({
 const messageSchema = z.object({
 	id: z.string(),
 	role: z.enum(["user", "assistant", "system"]),
-	content: z.string(),
+	content: z.string().nullable(),
+	images: z.string().nullable(), // JSON string
 	sequence: z.number(),
 	createdAt: z.string().datetime(),
 });
@@ -37,10 +38,15 @@ const updateChatSchema = z.object({
 	status: z.enum(["active", "archived"]).optional(),
 });
 
-const createMessageSchema = z.object({
-	role: z.enum(["user", "assistant", "system"]),
-	content: z.string().min(1),
-});
+const createMessageSchema = z
+	.object({
+		role: z.enum(["user", "assistant", "system"]),
+		content: z.string().optional(),
+		images: z.string().optional(), // JSON string
+	})
+	.refine((data) => data.content || data.images, {
+		message: "Either content or images must be provided",
+	});
 
 // List user's chats
 const listChats = createRoute({
@@ -274,6 +280,7 @@ chats.openapi(getChat, async (c) => {
 				id: message.id,
 				role: message.role as "user" | "assistant" | "system",
 				content: message.content,
+				images: message.images,
 				sequence: message.sequence,
 				createdAt: message.createdAt.toISOString(),
 			})),
@@ -503,7 +510,8 @@ chats.openapi(addMessage, async (c) => {
 		.values({
 			chatId: id,
 			role: body.role,
-			content: body.content,
+			content: body.content || null,
+			images: body.images || null,
 			sequence: nextSequence,
 		})
 		.returning();
@@ -520,6 +528,7 @@ chats.openapi(addMessage, async (c) => {
 				id: newMessage.id,
 				role: newMessage.role as "user" | "assistant" | "system",
 				content: newMessage.content,
+				images: newMessage.images,
 				sequence: newMessage.sequence,
 				createdAt: newMessage.createdAt.toISOString(),
 			},

apps/ui/public/changelog/gemini-2-5-flash-image-preview.png

@@ -27,7 +27,7 @@ import { useApi } from "@/lib/fetch-client";
 export interface Message {
 	id: string;
 	role: "user" | "assistant" | "system";
-	content: string;
+	content: string | null;
 	timestamp: Date;
 	images?: Array<{
 		type: "image_url";
@@ -89,6 +89,16 @@ export function PlaygroundClient() {
 				role: msg.role,
 				content: msg.content,
 				timestamp: new Date(msg.createdAt),
+				images: msg.images
+					? (() => {
+							try {
+								return JSON.parse(msg.images);
+							} catch (error) {
+								console.warn("Failed to parse images JSON:", msg.images, error);
+								return undefined;
+							}
+						})()
+					: undefined,
 			}));
 
 			// Preserve images from existing local messages when reloading from database
@@ -283,6 +293,7 @@ export function PlaygroundClient() {
 				const reader = response.body?.getReader();
 				const decoder = new TextDecoder();
 				let fullContent = "";
+				let finalImages: any[] = []; // Track final images received during streaming
 				let hasReceivedImages = false; // Track if we received images during streaming
 
 				if (reader) {
@@ -315,9 +326,11 @@ export function PlaygroundClient() {
 										let imagesToSet: any[] | undefined;
 										if (deltaImages && deltaImages.length > 0) {
 											imagesToSet = deltaImages;
+											finalImages = [...deltaImages]; // Track final images
 											hasReceivedImages = true; // Mark that we received images
 										} else if (images && images.length > 0) {
 											imagesToSet = images;
+											finalImages = [...images]; // Track final images
 											hasReceivedImages = true; // Mark that we received images
 										}
 
@@ -361,13 +374,20 @@ export function PlaygroundClient() {
 				}
 
 				// Save the complete assistant response to database
-				if (fullContent && chatId) {
+				if ((fullContent || finalImages.length > 0) && chatId) {
 					try {
 						await addMessage.mutateAsync({
 							params: {
 								path: { id: chatId },
 							},
-							body: { role: "assistant", content: fullContent },
+							body: {
+								role: "assistant",
+								content: fullContent || undefined,
+								images:
+									finalImages.length > 0
+										? JSON.stringify(finalImages)
+										: undefined,
+							},
 						});
 
 						// Only invalidate query if no images were received (to avoid overwriting image data with DB data)
@@ -384,7 +404,7 @@ export function PlaygroundClient() {
 			} else {
 				const data = await response.json();
 
-				const assistantContent = data.content || "";
+				const assistantContent = data.content ?? undefined;
 				const assistantImages = data.images || [];
 
 				addLocalMessage({
@@ -394,13 +414,20 @@ export function PlaygroundClient() {
 				});
 
 				// Save the assistant response to database
-				if (assistantContent && chatId) {
+				if ((assistantContent || assistantImages.length > 0) && chatId) {
 					try {
 						await addMessage.mutateAsync({
 							params: {
 								path: { id: chatId },
 							},
-							body: { role: "assistant", content: assistantContent },
+							body: {
+								role: "assistant",
+								content: assistantContent,
+								images:
+									assistantImages.length > 0
+										? JSON.stringify(assistantImages)
+										: undefined,
+							},
 						});
 
 						// Only invalidate query if no images (to avoid overwriting image data with DB data)

apps/ui/src/app/playground/playground-client.tsx

@@ -698,7 +698,7 @@ export function DashboardSidebar({
 				internal: false,
 			},
 			{
-				href: "https://llmgateway.io/playground",
+				href: "/playground",
 				label: "Playground",
 				icon: BotMessageSquare,
 				internal: false,

apps/ui/src/components/dashboard/dashboard-sidebar.tsx

@@ -28,7 +28,7 @@ import { cn } from "@/lib/utils";
 interface MessageType {
 	id: string;
 	role: "user" | "assistant" | "system";
-	content: string;
+	content: string | null;
 	timestamp: Date;
 	images?: Array<{
 		type: "image_url";
@@ -343,7 +343,7 @@ export function ChatUi({
 													message.role === "user" ? "right-0" : "left-0"
 												}`}
 												onClick={() =>
-													copyToClipboard(message.content, message.id)
+													copyToClipboard(message.content || "", message.id)
 												}
 											>
 												{copiedMessageId === message.id ? (

apps/ui/src/components/playground/chat-ui.tsx

@@ -13,6 +13,8 @@ image:
 
 We're thrilled to announce the addition of **Gemini 2.5 Flash Image Preview** - our **first image generation model** on LLM Gateway! This marks a significant milestone as we expand beyond text generation to visual AI capabilities.
 
+**[Try it now in the Playground](/playground?model=gemini-2.5-flash-image-preview)** 🎨
+
 ## 🎨 Introducing Image Generation
 
 **First of its Kind**: Gemini 2.5 Flash Image Preview is our inaugural image generation model, opening up exciting new possibilities for visual content creation through AI.

apps/ui/src/content/changelog/2025-08-26-gemini-2-5-flash-image-preview.md

@@ -16,7 +16,8 @@ export interface Chat {
 export interface ChatMessage {
 	id: string;
 	role: "user" | "assistant" | "system";
-	content: string;
+	content: string | null;
+	images: string | null; // JSON string from API
 	sequence: number;
 	createdAt: string;
 }

apps/ui/src/hooks/useChats.ts

@@ -2249,7 +2249,8 @@ export interface paths {
 								id: string;
 								/** @enum {string} */
 								role: "user" | "assistant" | "system";
-								content: string;
+								content: string | null;
+								images: string | null;
 								sequence: number;
 								/** Format: date-time */
 								createdAt: string;
@@ -2366,7 +2367,8 @@ export interface paths {
 					"application/json": {
 						/** @enum {string} */
 						role: "user" | "assistant" | "system";
-						content: string;
+						content?: string;
+						images?: string;
 					};
 				};
 			};
@@ -2382,7 +2384,8 @@ export interface paths {
 								id: string;
 								/** @enum {string} */
 								role: "user" | "assistant" | "system";
-								content: string;
+								content: string | null;
+								images: string | null;
 								sequence: number;
 								/** Format: date-time */
 								createdAt: string;

apps/ui/src/lib/api/v1.d.ts

@@ -6,6 +6,7 @@ export default [
 	{
 		rules: {
 			"@typescript-eslint/consistent-type-assertions": "off",
+			"@typescript-eslint/triple-slash-reference": "off",
 			"max-nested-callbacks": "off",
 			complexity: "off",
 			"max-depth": "off",

eslint.config.mjs

@@ -0,0 +1,2 @@
+ALTER TABLE "message" ALTER COLUMN "content" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "message" ADD COLUMN "images" text;