feat: Google Gemini image generation for project covers

Schema:
- SystemSettings: geminiApiKey, geminiModel, imageProvider fields
- imageProvider: "dalle" (default) or "gemini"

Gemini Client (packages/api/src/gemini-client.ts):
- Direct HTTP call to Gemini REST API with responseModalities: [TEXT, IMAGE]
- Returns base64 data URL
- Error parsing with user-friendly messages

Router (project.ts):
- generateCover: routes to DALL-E or Gemini based on imageProvider setting
- New isImageGenConfigured query returning { configured, provider }

Admin UI (SystemSettingsClient.tsx):
- "Image Generation" section with provider radio buttons (DALL-E / Gemini)
- Conditional fields: DALL-E config or Gemini API key + model
- Separate save button for image settings

Security:
- geminiApiKey sanitized in audit logs (SENSITIVE_FIELDS)
- API key stored server-side only, never sent to client

Co-Authored-By: claude-flow <ruv@ruv.net>

apps/web/src/components/admin/SystemSettingsClient.tsx

@@ -96,6 +96,13 @@ export function SystemSettingsClient() {
   const [dalleEndpoint, setDalleEndpoint] = useState("");
   const [dalleApiKey, setDalleApiKey] = useState("");
 
+  // Gemini / Image generation settings
+  type ImageProvider = "dalle" | "gemini";
+  const [imageProvider, setImageProvider] = useState<ImageProvider>("dalle");
+  const [geminiApiKey, setGeminiApiKey] = useState("");
+  const [geminiModel, setGeminiModel] = useState("");
+  const [imageSaved, setImageSaved] = useState(false);
+
   // SMTP settings
   const [smtpHost, setSmtpHost] = useState("");
   const [smtpPort, setSmtpPort] = useState(587);
@@ -144,6 +151,9 @@ export function SystemSettingsClient() {
       // DALL-E
       setDalleDeployment(settings.azureDalleDeployment ?? "");
       setDalleEndpoint(settings.azureDalleEndpoint ?? "");
+      // Image provider / Gemini
+      setImageProvider((settings.imageProvider ?? "dalle") as ImageProvider);
+      setGeminiModel(settings.geminiModel ?? "");
       // SMTP
       setSmtpHost(settings.smtpHost ?? "");
       setSmtpPort(settings.smtpPort ?? 587);
@@ -240,6 +250,13 @@ export function SystemSettingsClient() {
     },
   });
 
+  const saveImageMutation = trpc.settings.updateSystemSettings.useMutation({
+    onSuccess: () => {
+      setImageSaved(true);
+      setTimeout(() => setImageSaved(false), 3000);
+    },
+  });
+
   function handleSaveSmtp() {
     saveSmtpMutation.mutate({
       smtpHost: smtpHost || undefined,
@@ -259,6 +276,19 @@ export function SystemSettingsClient() {
     saveTimelineMutation.mutate({ timelineUndoMaxSteps: undoMaxSteps });
   }
 
+  function handleSaveImage() {
+    saveImageMutation.mutate({
+      imageProvider,
+      // DALL-E fields
+      azureDalleDeployment: dalleDeployment || undefined,
+      azureDalleEndpoint: provider === "azure" && dalleEndpoint ? dalleEndpoint : undefined,
+      ...(dalleApiKey ? { azureDalleApiKey: dalleApiKey } : {}),
+      // Gemini fields
+      ...(geminiApiKey ? { geminiApiKey } : {}),
+      geminiModel: geminiModel || undefined,
+    });
+  }
+
   function handleSaveAnonymization() {
     saveAnonymizationMutation.mutate({
       anonymizationEnabled,
@@ -295,9 +325,6 @@ export function SystemSettingsClient() {
       aiTemperature: temperature,
       aiSummaryPrompt: summaryPrompt || undefined,
       ...(apiKey ? { azureOpenAiApiKey: apiKey } : {}),
-      azureDalleDeployment: dalleDeployment,
-      azureDalleEndpoint: provider === "azure" && dalleEndpoint ? dalleEndpoint : undefined,
-      ...(dalleApiKey ? { azureDalleApiKey: dalleApiKey } : {}),
     });
   }
 
@@ -1018,67 +1045,159 @@ export function SystemSettingsClient() {
         </div>
       </div>
 
-      {/* ── DALL-E Image Generation ────────────────────────────────── */}
+      {/* ── Image Generation ────────────────────────────────── */}
       <div className={PANEL_CLASS}>
         <div>
           <h2 className="text-base font-semibold text-gray-900 dark:text-gray-100 flex items-center">
-            DALL-E Image Generation <InfoTooltip content="Configure the DALL-E model used for generating project cover art. Uses the same provider (OpenAI / Azure) as the chat model above." />
+            Image Generation <InfoTooltip content="Configure the image generation provider used for AI-generated project cover art." />
           </h2>
           <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
-            Used to generate AI cover art for projects. Leave blank to disable AI cover generation.
+            Used to generate AI cover art for projects. Configure at least one provider below.
           </p>
         </div>
 
-        <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-          <div>
-            <label className={LABEL_CLASS}>
-              <span className="flex items-center">
-                Deployment Name <InfoTooltip content="The DALL-E model deployment name (e.g. dall-e-3). For OpenAI this is the model name, for Azure it is the deployment name." />
-              </span>
+        {/* Provider selector */}
+        <div>
+          <label className={LABEL_CLASS}>Provider</label>
+          <div className="flex gap-4">
+            <label className="flex items-center gap-2 cursor-pointer">
+              <input
+                type="radio"
+                name="imageProvider"
+                value="dalle"
+                checked={imageProvider === "dalle"}
+                onChange={() => setImageProvider("dalle")}
+                className="accent-brand-600"
+              />
+              <span className="text-sm font-medium text-gray-700 dark:text-gray-300">DALL-E (Azure OpenAI / OpenAI)</span>
+            </label>
+            <label className="flex items-center gap-2 cursor-pointer">
+              <input
+                type="radio"
+                name="imageProvider"
+                value="gemini"
+                checked={imageProvider === "gemini"}
+                onChange={() => setImageProvider("gemini")}
+                className="accent-brand-600"
+              />
+              <span className="text-sm font-medium text-gray-700 dark:text-gray-300">Google Gemini</span>
             </label>
-            <input
-              type="text"
-              className={INPUT_CLASS}
-              value={dalleDeployment}
-              onChange={(e) => setDalleDeployment(e.target.value)}
-              placeholder="dall-e-3"
-            />
           </div>
+        </div>
 
-          {provider === "azure" && (
-            <>
+        {/* DALL-E settings (shown when DALL-E selected) */}
+        {imageProvider === "dalle" && (
+          <div className="space-y-4 rounded-xl border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-900/50">
+            <h3 className="text-sm font-semibold text-gray-700 dark:text-gray-300">DALL-E Configuration</h3>
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
               <div>
                 <label className={LABEL_CLASS}>
                   <span className="flex items-center">
-                    Endpoint <InfoTooltip content="Azure endpoint for the DALL-E deployment. Leave empty to use the same endpoint as the chat model." />
+                    Deployment Name <InfoTooltip content="The DALL-E model deployment name (e.g. dall-e-3). For OpenAI this is the model name, for Azure it is the deployment name." />
                   </span>
                 </label>
                 <input
                   type="text"
                   className={INPUT_CLASS}
-                  value={dalleEndpoint}
-                  onChange={(e) => setDalleEndpoint(e.target.value)}
-                  placeholder="Leave empty to use same endpoint as chat"
+                  value={dalleDeployment}
+                  onChange={(e) => setDalleDeployment(e.target.value)}
+                  placeholder="dall-e-3"
                 />
               </div>
 
+              {provider === "azure" && (
+                <>
+                  <div>
+                    <label className={LABEL_CLASS}>
+                      <span className="flex items-center">
+                        Endpoint <InfoTooltip content="Azure endpoint for the DALL-E deployment. Leave empty to use the same endpoint as the chat model." />
+                      </span>
+                    </label>
+                    <input
+                      type="text"
+                      className={INPUT_CLASS}
+                      value={dalleEndpoint}
+                      onChange={(e) => setDalleEndpoint(e.target.value)}
+                      placeholder="Leave empty to use same endpoint as chat"
+                    />
+                  </div>
+
+                  <div>
+                    <label className={LABEL_CLASS}>
+                      <span className="flex items-center">
+                        API Key{" "}
+                        <InfoTooltip content="API key for the DALL-E endpoint. Leave empty to use the same API key as the chat model." />
+                        <span className="ml-1 text-xs font-normal text-gray-400">(optional)</span>
+                      </span>
+                    </label>
+                    <input
+                      type="password"
+                      className={INPUT_CLASS}
+                      value={dalleApiKey}
+                      onChange={(e) => setDalleApiKey(e.target.value)}
+                      placeholder="Leave empty to use same API key as chat"
+                    />
+                  </div>
+                </>
+              )}
+            </div>
+            {settings?.hasDalleApiKey && (
+              <p className="text-xs text-green-600 dark:text-green-400">A separate DALL-E API key is stored.</p>
+            )}
+          </div>
+        )}
+
+        {/* Gemini settings (shown when Gemini selected) */}
+        {imageProvider === "gemini" && (
+          <div className="space-y-4 rounded-xl border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-900/50">
+            <h3 className="text-sm font-semibold text-gray-700 dark:text-gray-300">Google Gemini Configuration</h3>
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
               <div>
                 <label className={LABEL_CLASS}>
                   <span className="flex items-center">
-                    API Key{" "}
-                    <InfoTooltip content="API key for the DALL-E endpoint. Leave empty to use the same API key as the chat model." />
-                    <span className="ml-1 text-xs font-normal text-gray-400">(optional)</span>
+                    API Key <InfoTooltip content="Google Gemini API key from Google AI Studio (aistudio.google.com)." />
                   </span>
                 </label>
                 <input
                   type="password"
                   className={INPUT_CLASS}
-                  value={dalleApiKey}
-                  onChange={(e) => setDalleApiKey(e.target.value)}
-                  placeholder="Leave empty to use same API key as chat"
+                  value={geminiApiKey}
+                  onChange={(e) => setGeminiApiKey(e.target.value)}
+                  placeholder={settings?.hasGeminiApiKey ? "••••••••  (key is stored)" : "Enter Gemini API key"}
+                />
+                {settings?.hasGeminiApiKey && !geminiApiKey && (
+                  <p className="text-xs text-green-600 dark:text-green-400 mt-1">API key is stored.</p>
+                )}
+              </div>
+              <div>
+                <label className={LABEL_CLASS}>
+                  <span className="flex items-center">
+                    Model <InfoTooltip content="Gemini model for image generation. The default model supports image output." />
+                  </span>
+                </label>
+                <input
+                  type="text"
+                  className={INPUT_CLASS}
+                  value={geminiModel}
+                  onChange={(e) => setGeminiModel(e.target.value)}
+                  placeholder="gemini-2.0-flash-preview-image-generation"
                 />
               </div>
-            </>
+            </div>
+          </div>
+        )}
+
+        <div className="flex items-center gap-3 pt-1">
+          <button
+            type="button"
+            className={PRIMARY_BUTTON_CLASS}
+            disabled={saveImageMutation.isPending}
+            onClick={handleSaveImage}
+          >
+            {saveImageMutation.isPending ? "Saving..." : "Save Image Settings"}
+          </button>
+          {imageSaved && (
+            <span className="text-sm font-medium text-green-600 dark:text-green-400">Saved</span>
           )}
         </div>
       </div>

apps/web/src/components/projects/CoverArtSection.tsx

@@ -25,7 +25,7 @@ export function CoverArtSection({ projectId, coverImageUrl, coverFocusY = 50, pr
   const fileInputRef = useRef<HTMLInputElement>(null);
   const utils = trpc.useUtils();
 
-  const { data: dalleStatus } = trpc.project.isDalleConfigured.useQuery();
+  const { data: imageGenStatus } = trpc.project.isImageGenConfigured.useQuery();
   const generateMutation = trpc.project.generateCover.useMutation();
   const uploadMutation = trpc.project.uploadCover.useMutation();
   const removeMutation = trpc.project.removeCover.useMutation();
@@ -207,7 +207,7 @@ export function CoverArtSection({ projectId, coverImageUrl, coverFocusY = 50, pr
           )}
 
           {/* Generate with AI */}
-          {dalleStatus?.configured && (
+          {imageGenStatus?.configured && (
             <button
               type="button"
               onClick={() => {

packages/api/src/gemini-client.ts

@@ -0,0 +1,94 @@
+type GeminiSettings = {
+  geminiApiKey?: string | null;
+  geminiModel?: string | null;
+};
+
+/** Returns true if the settings have a Gemini API key configured. */
+export function isGeminiConfigured(settings: GeminiSettings | null | undefined): boolean {
+  return !!settings?.geminiApiKey;
+}
+
+/**
+ * Generates an image using the Google Gemini API.
+ * @returns A base64 data URL of the generated image.
+ */
+export async function generateGeminiImage(
+  apiKey: string,
+  prompt: string,
+  model = "gemini-2.0-flash-preview-image-generation",
+): Promise<string> {
+  const fullPrompt = `Generate a professional, cinematic cover image for a 3D production project. ${prompt}`;
+
+  const response = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: fullPrompt }] }],
+        generationConfig: { responseModalities: ["TEXT", "IMAGE"] },
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    const body = await response.text();
+    let msg = body;
+    try {
+      const parsed = JSON.parse(body) as { error?: { message?: string } };
+      if (parsed.error?.message) msg = parsed.error.message;
+    } catch {
+      /* keep raw */
+    }
+    throw new Error(`HTTP ${response.status}: ${msg}`);
+  }
+
+  const data = (await response.json()) as {
+    candidates?: Array<{
+      content?: {
+        parts?: Array<{
+          inlineData?: { data: string; mimeType: string };
+          text?: string;
+        }>;
+      };
+    }>;
+  };
+
+  const imagePart = data.candidates?.[0]?.content?.parts?.find(
+    (p) => p.inlineData,
+  );
+
+  if (!imagePart?.inlineData?.data) {
+    throw new Error("No image data returned from Gemini");
+  }
+
+  const base64 = imagePart.inlineData.data;
+  const mimeType = imagePart.inlineData.mimeType ?? "image/png";
+  return `data:${mimeType};base64,${base64}`;
+}
+
+/** Turns Gemini API errors into actionable human-readable messages. */
+export function parseGeminiError(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  const lower = msg.toLowerCase();
+
+  if (lower.includes("400") || lower.includes("invalid")) {
+    return "Invalid request — check the Gemini model name and prompt.";
+  }
+  if (lower.includes("401") || lower.includes("unauthorized") || lower.includes("api_key_invalid") || lower.includes("api key not valid")) {
+    return "Invalid API key — make sure you copied it correctly from Google AI Studio.";
+  }
+  if (lower.includes("403") || lower.includes("forbidden") || lower.includes("permission")) {
+    return "Access denied — your API key may not have permission to use image generation.";
+  }
+  if (lower.includes("404") || lower.includes("not found")) {
+    return "Model not found — verify the Gemini model name is correct.";
+  }
+  if (lower.includes("429") || lower.includes("rate limit") || lower.includes("quota")) {
+    return "Rate limit or quota exceeded — wait a moment and try again.";
+  }
+  if (lower.includes("econnrefused") || lower.includes("enotfound") || lower.includes("fetch failed")) {
+    return "Cannot reach the Gemini API — check your network connection.";
+  }
+  return msg.replace(/^Error: /, "").slice(0, 300);
+}

packages/api/src/router/project.ts

@@ -12,6 +12,7 @@ import { buildDynamicFieldWhereClauses } from "./custom-field-filters.js";
 import { loadProjectPlanningReadModel } from "./project-planning-read-model.js";
 import { adminProcedure, controllerProcedure, createTRPCRouter, managerProcedure, protectedProcedure, requirePermission } from "../trpc.js";
 import { createDalleClient, isDalleConfigured, parseAiError } from "../ai-client.js";
+import { generateGeminiImage, isGeminiConfigured, parseGeminiError } from "../gemini-client.js";
 import { invalidateDashboardCache } from "../lib/cache.js";
 import { dispatchWebhooks } from "../lib/webhook-dispatcher.js";
 
@@ -434,10 +435,14 @@ export const projectRouter = createTRPCRouter({
         where: { id: "singleton" },
       });
 
-      if (!isDalleConfigured(settings)) {
+      const imageProvider = settings?.imageProvider ?? "dalle";
+      const useGemini = imageProvider === "gemini" && isGeminiConfigured(settings);
+      const useDalle = imageProvider === "dalle" && isDalleConfigured(settings);
+
+      if (!useGemini && !useDalle) {
         throw new TRPCError({
           code: "PRECONDITION_FAILED",
-          message: "DALL-E is not configured. Set up the DALL-E deployment in Admin → Settings.",
+          message: "No image provider configured. Set up DALL-E or Gemini in Admin → Settings.",
         });
       }
 
@@ -447,36 +452,53 @@ export const projectRouter = createTRPCRouter({
         ? `${basePrompt} Additional direction: ${input.prompt}`
         : basePrompt;
 
-      const dalleClient = createDalleClient(settings!);
-      const model = settings!.aiProvider === "azure" ? settings!.azureDalleDeployment! : "dall-e-3";
+      let coverImageUrl: string;
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let response: any;
-      try {
-        response = await dalleClient.images.generate({
-          model,
-          prompt: finalPrompt,
-          size: "1024x1024",
-          n: 1,
-          response_format: "b64_json",
-        });
-      } catch (err) {
-        throw new TRPCError({
-          code: "INTERNAL_SERVER_ERROR",
-          message: `DALL-E error: ${parseAiError(err)}`,
-        });
+      if (useGemini) {
+        try {
+          coverImageUrl = await generateGeminiImage(
+            settings!.geminiApiKey!,
+            finalPrompt,
+            settings!.geminiModel ?? undefined,
+          );
+        } catch (err) {
+          throw new TRPCError({
+            code: "INTERNAL_SERVER_ERROR",
+            message: `Gemini error: ${parseGeminiError(err)}`,
+          });
+        }
+      } else {
+        const dalleClient = createDalleClient(settings!);
+        const model = settings!.aiProvider === "azure" ? settings!.azureDalleDeployment! : "dall-e-3";
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let response: any;
+        try {
+          response = await dalleClient.images.generate({
+            model,
+            prompt: finalPrompt,
+            size: "1024x1024",
+            n: 1,
+            response_format: "b64_json",
+          });
+        } catch (err) {
+          throw new TRPCError({
+            code: "INTERNAL_SERVER_ERROR",
+            message: `DALL-E error: ${parseAiError(err)}`,
+          });
+        }
+
+        const b64 = response.data?.[0]?.b64_json;
+        if (!b64) {
+          throw new TRPCError({
+            code: "INTERNAL_SERVER_ERROR",
+            message: "No image data returned from DALL-E",
+          });
+        }
+
+        coverImageUrl = `data:image/png;base64,${b64}`;
       }
 
-      const b64 = response.data?.[0]?.b64_json;
-      if (!b64) {
-        throw new TRPCError({
-          code: "INTERNAL_SERVER_ERROR",
-          message: "No image data returned from DALL-E",
-        });
-      }
-
-      const coverImageUrl = `data:image/png;base64,${b64}`;
-
       await ctx.db.project.update({
         where: { id: input.projectId },
         data: { coverImageUrl },
@@ -552,11 +574,28 @@ export const projectRouter = createTRPCRouter({
       return { ok: true };
     }),
 
+  isImageGenConfigured: protectedProcedure
+    .query(async ({ ctx }) => {
+      const settings = await ctx.db.systemSettings.findUnique({
+        where: { id: "singleton" },
+      });
+      const imageProvider = settings?.imageProvider ?? "dalle";
+      const configured = imageProvider === "gemini"
+        ? isGeminiConfigured(settings)
+        : isDalleConfigured(settings);
+      return { configured, provider: imageProvider };
+    }),
+
+  /** @deprecated Use isImageGenConfigured instead */
   isDalleConfigured: protectedProcedure
     .query(async ({ ctx }) => {
       const settings = await ctx.db.systemSettings.findUnique({
         where: { id: "singleton" },
       });
-      return { configured: isDalleConfigured(settings) };
+      const imageProvider = settings?.imageProvider ?? "dalle";
+      const configured = imageProvider === "gemini"
+        ? isGeminiConfigured(settings)
+        : isDalleConfigured(settings);
+      return { configured };
     }),
 });

packages/api/src/router/settings.ts

@@ -12,6 +12,7 @@ const SENSITIVE_FIELDS = new Set([
   "smtpPassword",
   "azureDalleApiKey",
   "anonymizationSeed",
+  "geminiApiKey",
 ]);
 
 export const settingsRouter = createTRPCRouter({
@@ -55,6 +56,11 @@ export const settingsRouter = createTRPCRouter({
       azureDalleDeployment: settings?.azureDalleDeployment ?? null,
       azureDalleEndpoint: settings?.azureDalleEndpoint ?? null,
       hasDalleApiKey: !!settings?.azureDalleApiKey,
+      // Gemini
+      geminiModel: settings?.geminiModel ?? "gemini-2.0-flash-preview-image-generation",
+      hasGeminiApiKey: !!settings?.geminiApiKey,
+      // Image provider
+      imageProvider: settings?.imageProvider ?? "dalle",
       // Vacation defaults
       vacationDefaultDays: settings?.vacationDefaultDays ?? 28,
       // Timeline
@@ -103,6 +109,11 @@ export const settingsRouter = createTRPCRouter({
         azureDalleDeployment: z.string().optional(),
         azureDalleEndpoint: z.string().url().optional().or(z.literal("")),
         azureDalleApiKey: z.string().optional(),
+        // Gemini image generation
+        geminiApiKey: z.string().optional(),
+        geminiModel: z.string().optional(),
+        // Image provider selection
+        imageProvider: z.enum(["dalle", "gemini"]).optional(),
         // Vacation
         vacationDefaultDays: z.number().int().min(0).max(365).optional(),
         // Timeline
@@ -155,6 +166,14 @@ export const settingsRouter = createTRPCRouter({
         data.azureDalleEndpoint = input.azureDalleEndpoint || null;
       if (input.azureDalleApiKey !== undefined)
         data.azureDalleApiKey = input.azureDalleApiKey || null;
+      // Gemini
+      if (input.geminiApiKey !== undefined)
+        data.geminiApiKey = input.geminiApiKey || null;
+      if (input.geminiModel !== undefined)
+        data.geminiModel = input.geminiModel || null;
+      // Image provider
+      if (input.imageProvider !== undefined)
+        data.imageProvider = input.imageProvider;
       // Vacation
       if (input.vacationDefaultDays !== undefined) data.vacationDefaultDays = input.vacationDefaultDays;
       // Timeline

packages/db/prisma/schema.prisma

@@ -1447,6 +1447,10 @@ model SystemSettings {
   azureDalleDeployment    String?  // e.g. "dall-e-3" — Azure DALL-E deployment name
   azureDalleEndpoint      String?  // Optional: separate endpoint for DALL-E (if different from chat)
   azureDalleApiKey        String?  // Optional: separate API key for DALL-E
+  // Gemini image generation
+  geminiApiKey            String?
+  geminiModel             String?  @default("gemini-2.0-flash-preview-image-generation")
+  imageProvider           String?  @default("dalle")  // "dalle" | "gemini"
   updatedAt               DateTime @updatedAt
 
   @@map("system_settings")