myaidev-method 0.3.4 → 0.3.5

package/skills/myai-visual-generator/scripts/visual-generation-utils.js

@@ -0,0 +1,1272 @@
+/**
+ * Visual Content Generation Utilities
+ *
+ * Provides image and video generation capabilities using:
+ *
+ * RECOMMENDED SOTA MODELS:
+ * - Google Gemini 3.0 Pro Image ("Nano Banana") - fast, cost-effective
+ * - OpenAI GPT Image 1.5 - state-of-the-art quality, best text rendering
+ *
+ * ADDITIONAL MODELS:
+ * - Google Imagen 3 - premium quality via Gemini API
+ * - Black Forest Labs FLUX 2 (pro, flex, dev) - excellent quality
+ * - Google Veo 3 - latest video generation
+ *
+ * Authentication: Uses simple API keys (GEMINI_API_KEY, OPENAI_API_KEY, FAL_KEY)
+ *
+ * Platform support: Claude Code, Gemini CLI, Codex CLI
+ *
+ * @module visual-generation-utils
+ */
+
+import fs from "fs-extra";
+import path from "path";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+// API Configuration
+const GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta";
+const OPENAI_API_BASE = "https://api.openai.com/v1";
+
+// Gemini Models for image generation
+const GEMINI_IMAGE_MODEL = "gemini-3-pro-image-preview"; // Gemini 3.0 "Nano Banana" preview
+const GEMINI_IMAGEN_MODEL = "imagen-3.0-generate-002"; // Imagen via Gemini API
+
+// OpenAI GPT Image Models (SOTA)
+const OPENAI_IMAGE_MODELS = {
+	"gpt-image-1.5": "gpt-image-1.5", // State-of-the-art (recommended)
+	"gpt-image-1": "gpt-image-1", // Main model
+	"gpt-image-1-mini": "gpt-image-1-mini", // Cost-effective option
+};
+
+// FLUX 2 Models (via Fal.ai or BFL API)
+export const FLUX2_MODELS = {
+	"flux2-pro": "fal-ai/flux-2-pro", // State-of-the-art quality, fastest, lowest cost
+	"flux2-flex": "fal-ai/flux-2-flex", // Developer-controlled parameters
+	"flux2-dev": "fal-ai/flux-2-dev", // 32B open-weight model
+	// Legacy FLUX 1.x models (still available)
+	"flux-pro": "fal-ai/flux-pro/v1.1-ultra",
+	"flux-dev": "fal-ai/flux/dev",
+
+	// nano banana models
+	"nano-banana-pro": "fal-ai/nano-banana-pro",
+};
+
+// Pricing (USD per image/video)
+const PRICING = {
+	// SOTA Models (Recommended)
+	gemini: 0.02, // Gemini 3.0 Pro Image "Nano Banana" - fast, cheap
+	"gpt-image-1.5": 0.19, // OpenAI GPT Image 1.5 - SOTA quality (high quality)
+	"gpt-image-1.5-medium": 0.07, // GPT Image 1.5 medium quality
+	"gpt-image-1.5-low": 0.02, // GPT Image 1.5 low quality
+	"gpt-image-1": 0.19, // OpenAI GPT Image 1 (high quality)
+	"gpt-image-1-mini": 0.02, // OpenAI GPT Image 1 Mini - budget option
+	// Additional Models
+	imagen: 0.03, // Imagen 3 (Gemini API)
+	nano_banana_pro: 0.15, // Nano Banana Pro (Fal API)
+	// FLUX 2 pricing
+	flux2_pro: 0.05, // FLUX 2 Pro
+	flux2_flex: 0.04, // FLUX 2 Flex
+	flux2_dev: 0.025, // FLUX 2 Dev
+	// Legacy FLUX 1.x
+	flux_pro: 0.06, // FLUX Pro v1.1 Ultra
+	flux_dev: 0.025, // FLUX Dev (per megapixel)
+	// Video
+	veo3: 0.4, // Veo 3 (per second)
+};
+
+/**
+ * Validate that required API keys are configured
+ *
+ * @returns {Object} Validation results
+ */
+export function validateAPIKeys() {
+	// Support both GEMINI_API_KEY (preferred) and GOOGLE_API_KEY (legacy)
+	const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+	const openaiKey = process.env.OPENAI_API_KEY;
+	const falKey = process.env.FAL_KEY;
+	const bflKey = process.env.BFL_API_KEY; // Black Forest Labs direct API
+
+	const hasGemini = !!(geminiKey && geminiKey.length > 20);
+	const hasOpenAI = !!(openaiKey && openaiKey.length > 20);
+	const hasFal = !!(falKey && falKey.length > 20);
+	const hasBFL = !!(bflKey && bflKey.length > 20);
+
+	const availableServices = [];
+	if (hasGemini) {
+		availableServices.push("gemini", "imagen");
+	}
+	if (hasOpenAI) {
+		availableServices.push("gpt-image-1.5", "gpt-image-1", "gpt-image-1-mini");
+	}
+	if (hasFal || hasBFL) {
+		availableServices.push(
+			"nano-banana-pro",
+			"flux2-pro",
+			"flux2-flex",
+			"flux2-dev",
+			"flux-pro",
+			"flux-dev",
+			"veo3",
+		);
+	}
+
+	return {
+		hasGemini,
+		hasGoogle: hasGemini, // Legacy compatibility
+		hasOpenAI,
+		hasFal,
+		hasBFL,
+		hasAny: hasGemini || hasOpenAI || hasFal || hasBFL,
+		availableServices,
+	};
+}
+
+/**
+ * Estimate cost for image/video generation
+ *
+ * @param {string} service - Service name
+ * @param {Object} options - Generation options
+ * @returns {number} Estimated cost in USD
+ */
+export function estimateCost(service, options = {}) {
+	const { quality = "high" } = options;
+
+	switch (service) {
+		case "gemini":
+			return PRICING.gemini;
+
+		case "imagen":
+			return PRICING.imagen;
+
+		// OpenAI GPT Image models - cost varies by quality
+		case "gpt-image-1.5":
+			if (quality === "low") return PRICING["gpt-image-1.5-low"];
+			if (quality === "medium") return PRICING["gpt-image-1.5-medium"];
+			return PRICING["gpt-image-1.5"]; // high quality default
+
+		case "gpt-image-1":
+			return PRICING["gpt-image-1"];
+
+		case "gpt-image-1-mini":
+			return PRICING["gpt-image-1-mini"];
+
+		case "flux2-pro":
+			return PRICING.flux2_pro;
+
+		case "flux2-flex":
+			return PRICING.flux2_flex;
+
+		case "flux2-dev":
+			return PRICING.flux2_dev;
+
+		case "flux":
+		case "flux-pro":
+			return PRICING.flux_pro;
+
+		case "flux-dev":
+			return PRICING.flux_dev;
+
+		case "nano-banana-pro":
+			return PRICING.nano_banana_pro;
+
+		case "veo3":
+		case "veo3-fast":
+			return PRICING.veo3; // per second, will multiply by duration
+
+		default:
+			return 0;
+	}
+}
+
+/**
+ * Select best available service based on preferences
+ *
+ * @param {string} preferred - Preferred service name
+ * @returns {string} Selected service name
+ * @throws {Error} If no API keys are configured
+ */
+export function selectBestService(preferred = "gemini") {
+	const { availableServices, hasAny } = validateAPIKeys();
+
+	if (!hasAny) {
+		throw new Error(
+			"No API keys configured. Set GEMINI_API_KEY, OPENAI_API_KEY, or FAL_KEY in your environment.",
+		);
+	}
+
+	// Return preferred service if available
+	if (availableServices.includes(preferred)) {
+		return preferred;
+	}
+
+	// Fallback to first available service
+	return availableServices[0];
+}
+
+/**
+ * Generate image using Google Gemini API
+ * Uses gemini-3-pro-image-preview model ("Nano Banana") with simple API key auth
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.imageSize - Image size (1K, 2K)
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated image data
+ */
+export async function generateImageGemini(prompt, options = {}) {
+	const { imageSize = "1K", maxRetries = 3 } = options;
+
+	const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"GEMINI_API_KEY not configured. Set GEMINI_API_KEY in your environment.",
+		);
+	}
+
+	const endpoint = `${GEMINI_API_BASE}/models/${GEMINI_IMAGE_MODEL}:generateContent`;
+
+	const requestBody = {
+		contents: [
+			{
+				role: "user",
+				parts: [
+					{
+						text: prompt,
+					},
+				],
+			},
+		],
+		generationConfig: {
+			responseModalities: ["IMAGE", "TEXT"],
+			imageConfig: {
+				image_size: imageSize,
+			},
+		},
+	};
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const response = await fetch(`${endpoint}?key=${apiKey}`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify(requestBody),
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`Gemini API error: ${response.status} - ${errorText}`);
+			}
+
+			const data = await response.json();
+
+			// Handle streaming response format (array of candidates)
+			const candidates = Array.isArray(data) ? data : data.candidates || [data];
+
+			for (const candidate of candidates) {
+				const content = candidate.content || candidate;
+				const parts = content.parts || [];
+
+				for (const part of parts) {
+					// Check for inline image data
+					if (part.inlineData && part.inlineData.data) {
+						return {
+							data: part.inlineData.data,
+							mimeType: part.inlineData.mimeType || "image/png",
+							service: "gemini",
+							model: GEMINI_IMAGE_MODEL,
+							cost: PRICING.gemini,
+						};
+					}
+
+					// Check for file data reference
+					if (part.fileData && part.fileData.fileUri) {
+						const imageResponse = await fetch(part.fileData.fileUri);
+						const imageBuffer = await imageResponse.arrayBuffer();
+						const base64Data = Buffer.from(imageBuffer).toString("base64");
+
+						return {
+							data: base64Data,
+							mimeType: part.fileData.mimeType || "image/png",
+							service: "gemini",
+							model: GEMINI_IMAGE_MODEL,
+							cost: PRICING.gemini,
+						};
+					}
+				}
+			}
+
+			throw new Error("No image data in Gemini response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ Gemini attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Generate image using Google Imagen 3 (via Gemini API)
+ * Premium quality image generation with simple API key authentication
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.aspectRatio - Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
+ * @param {number} options.numberOfImages - Number of images to generate (1-4)
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated image data
+ */
+export async function generateImageImagen(prompt, options = {}) {
+	const { aspectRatio = "1:1", numberOfImages = 1, maxRetries = 3 } = options;
+
+	const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"GEMINI_API_KEY not configured. Set GEMINI_API_KEY in your environment.",
+		);
+	}
+
+	const endpoint = `${GEMINI_API_BASE}/models/${GEMINI_IMAGEN_MODEL}:generateImages`;
+
+	const requestBody = {
+		prompt: prompt,
+		config: {
+			numberOfImages: Math.min(numberOfImages, 4),
+			aspectRatio: aspectRatio,
+			safetyFilterLevel: "BLOCK_MEDIUM_AND_ABOVE",
+		},
+	};
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const response = await fetch(`${endpoint}?key=${apiKey}`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify(requestBody),
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`Imagen API error: ${response.status} - ${errorText}`);
+			}
+
+			const data = await response.json();
+
+			// Imagen returns images array with base64 encoded data
+			if (data.generatedImages && data.generatedImages[0]) {
+				const image = data.generatedImages[0];
+
+				if (image.image && image.image.imageBytes) {
+					return {
+						data: image.image.imageBytes,
+						mimeType: "image/png",
+						service: "imagen",
+						model: GEMINI_IMAGEN_MODEL,
+						cost: PRICING.imagen,
+					};
+				}
+			}
+
+			// Alternative response format
+			if (data.images && data.images[0]) {
+				const image = data.images[0];
+
+				if (image.bytesBase64Encoded || image.imageBytes) {
+					return {
+						data: image.bytesBase64Encoded || image.imageBytes,
+						mimeType: "image/png",
+						service: "imagen",
+						model: GEMINI_IMAGEN_MODEL,
+						cost: PRICING.imagen,
+					};
+				}
+			}
+
+			throw new Error("No image data in Imagen response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ Imagen attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Generate image using OpenAI GPT Image API
+ * State-of-the-art image generation with best text rendering
+ *
+ * Features:
+ * - Best-in-class text rendering in images
+ * - Multiple quality tiers (low, medium, high)
+ * - Transparency support (PNG with transparent background)
+ * - Multiple output formats (PNG, JPEG, WebP)
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.model - Model (gpt-image-1.5, gpt-image-1, gpt-image-1-mini)
+ * @param {string} options.size - Image size (1024x1024, 1536x1024, 1024x1536, auto)
+ * @param {string} options.quality - Quality level (low, medium, high, auto)
+ * @param {string} options.outputFormat - Output format (png, jpeg, webp)
+ * @param {string} options.background - Background type (transparent, opaque, auto)
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated image data
+ */
+export async function generateImageOpenAI(prompt, options = {}) {
+	const {
+		model = "gpt-image-1.5",
+		size = "1024x1024",
+		quality = "high",
+		outputFormat = "png",
+		background = "auto",
+		maxRetries = 3,
+	} = options;
+
+	const apiKey = process.env.OPENAI_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"OPENAI_API_KEY not configured. Get your key from https://platform.openai.com/api-keys",
+		);
+	}
+
+	const endpoint = `${OPENAI_API_BASE}/images/generations`;
+
+	const requestBody = {
+		model: OPENAI_IMAGE_MODELS[model] || model,
+		prompt: prompt,
+		n: 1,
+		size: size,
+		quality: quality,
+		output_format: outputFormat,
+	};
+
+	// Add background for PNG format (transparency support)
+	if (outputFormat === "png" && background !== "auto") {
+		requestBody.background = background;
+	}
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+				body: JSON.stringify(requestBody),
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				let errorMessage = `OpenAI API error: ${response.status}`;
+				try {
+					const errorData = JSON.parse(errorText);
+					errorMessage = errorData.error?.message || errorMessage;
+				} catch {
+					errorMessage = `${errorMessage} - ${errorText}`;
+				}
+				throw new Error(errorMessage);
+			}
+
+			const data = await response.json();
+
+			// OpenAI returns base64-encoded image data
+			if (data.data && data.data[0]) {
+				const imageData = data.data[0];
+
+				// Handle base64 response (primary)
+				if (imageData.b64_json) {
+					return {
+						data: imageData.b64_json,
+						mimeType:
+							outputFormat === "jpeg"
+								? "image/jpeg"
+								: outputFormat === "webp"
+									? "image/webp"
+									: "image/png",
+						service: "openai",
+						model: model,
+						cost: estimateCost(model, { quality }),
+						revisedPrompt: imageData.revised_prompt,
+					};
+				}
+
+				// Handle URL response (fallback)
+				if (imageData.url) {
+					const imageResponse = await fetch(imageData.url);
+					const imageBuffer = await imageResponse.arrayBuffer();
+					const base64Data = Buffer.from(imageBuffer).toString("base64");
+
+					return {
+						data: base64Data,
+						mimeType:
+							outputFormat === "jpeg"
+								? "image/jpeg"
+								: outputFormat === "webp"
+									? "image/webp"
+									: "image/png",
+						service: "openai",
+						model: model,
+						cost: estimateCost(model, { quality }),
+						revisedPrompt: imageData.revised_prompt,
+					};
+				}
+			}
+
+			throw new Error("No image data in OpenAI response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ OpenAI attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Generate image using FLUX 2 (via Fal.ai)
+ * State-of-the-art image generation from Black Forest Labs
+ *
+ * Features:
+ * - Multi-reference support (up to 10 images)
+ * - Enhanced photorealism
+ * - Complex typography and UI mockups
+ * - Image editing up to 4 megapixels
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.model - FLUX 2 model (flux2-pro, flux2-flex, flux2-dev)
+ * @param {string} options.size - Image size (square, landscape, portrait)
+ * @param {number} options.steps - Number of inference steps (flux2-flex only)
+ * @param {number} options.guidance - Guidance scale (flux2-flex only)
+ * @param {Array<string>} options.referenceImages - Reference image URLs (up to 10)
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated image data
+ */
+export async function generateImageFlux2(prompt, options = {}) {
+	const {
+		model = "flux2-pro",
+		size = "square",
+		steps = 28,
+		guidance = 3.5,
+		referenceImages = [],
+		maxRetries = 3,
+	} = options;
+
+	const apiKey = process.env.FAL_KEY || process.env.BFL_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"FAL_KEY not configured. Get your key from https://fal.ai/dashboard/keys",
+		);
+	}
+
+	// Import fal.ai client
+	const { fal } = await import("@fal-ai/client");
+	fal.config({ credentials: apiKey });
+
+	// Get endpoint for model
+	const endpoint = FLUX2_MODELS[model] || FLUX2_MODELS["flux2-pro"];
+
+	// Build input based on model capabilities
+	const input = {
+		prompt: prompt,
+		image_size: size === "1024x1024" ? "square" : size,
+		num_images: 1,
+	};
+
+	// FLUX 2 Flex supports custom parameters
+	if (model === "flux2-flex") {
+		input.num_inference_steps = steps;
+		input.guidance_scale = guidance;
+	}
+
+	// Add reference images if provided (FLUX 2 multi-reference feature)
+	if (referenceImages.length > 0) {
+		input.reference_images = referenceImages.slice(0, 10); // Max 10
+	}
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const result = await fal.subscribe(endpoint, {
+				input,
+				logs: false,
+			});
+
+			// Extract image from result
+			let imageUrl;
+			let contentType = "image/png";
+
+			if (result.data?.images?.[0]) {
+				imageUrl = result.data.images[0].url;
+				contentType = result.data.images[0].content_type || "image/png";
+			} else if (result.images?.[0]) {
+				imageUrl = result.images[0].url;
+				contentType = result.images[0].content_type || "image/png";
+			} else if (result.image?.url) {
+				imageUrl = result.image.url;
+			}
+
+			if (imageUrl) {
+				// Fetch and convert to base64
+				const imageResponse = await fetch(imageUrl);
+				const imageBuffer = await imageResponse.arrayBuffer();
+				const base64Data = Buffer.from(imageBuffer).toString("base64");
+
+				return {
+					data: base64Data,
+					mimeType: contentType,
+					service: "flux2",
+					model: model,
+					cost: PRICING[model.replaceAll("-", "_")] || PRICING.flux2_pro,
+				};
+			}
+
+			throw new Error("No image data in FLUX 2 response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ FLUX 2 attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Generate image using legacy FLUX 1.x (via Fal.ai)
+ * Still available for backwards compatibility
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.model - FLUX model (nano-banana-pro, flux-pro, flux-dev)
+ * @param {string} options.size - Image size
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated image data
+ */
+export async function generateImageFal(prompt, options = {}) {
+	const {
+		model = "nano-banana-pro",
+		size = "1024x1024",
+		maxRetries = 3,
+	} = options;
+
+	const apiKey = process.env.FAL_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"FAL_KEY not configured. Get your key from https://fal.ai/dashboard/keys",
+		);
+	}
+
+	const { fal } = await import("@fal-ai/client");
+	fal.config({ credentials: apiKey });
+
+	const endpoint = FLUX2_MODELS[model] || FLUX2_MODELS["flux-pro"];
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const result = await fal.subscribe(endpoint, {
+				input: {
+					prompt: prompt,
+					image_size: size === "1024x1024" ? "square" : "landscape",
+					num_images: 1,
+				},
+				logs: false,
+			});
+
+			let imageUrl;
+			let contentType = "image/png";
+
+			if (result.data?.images?.[0]) {
+				imageUrl = result.data.images[0].url;
+				contentType = result.data.images[0].content_type || "image/png";
+			} else if (result.images?.[0]) {
+				imageUrl = result.images[0].url;
+				contentType = result.images[0].content_type || "image/png";
+			} else if (result.image?.url) {
+				imageUrl = result.image.url;
+			}
+
+			if (imageUrl) {
+				const imageResponse = await fetch(imageUrl);
+				const imageBuffer = await imageResponse.arrayBuffer();
+				const base64Data = Buffer.from(imageBuffer).toString("base64");
+
+				return {
+					data: base64Data,
+					mimeType: contentType,
+					service: "fal",
+					model: model,
+					cost: PRICING[model.replaceAll("-", "_")] || PRICING.flux_pro,
+				};
+			}
+
+			throw new Error("No image data in Fal.ai response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ Fal.ai attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Generate video using Veo 3 (via Fal.ai)
+ * Latest video generation with outstanding quality
+ *
+ * @param {string} prompt - Video description
+ * @param {Object} options - Generation options
+ * @param {string} options.model - Model (veo3, veo3-fast)
+ * @param {number} options.duration - Video duration in seconds
+ * @param {string} options.aspectRatio - Aspect ratio
+ * @param {number} options.maxRetries - Maximum retry attempts
+ * @returns {Promise<Object>} Generated video data
+ */
+export async function generateVideoVeo3(prompt, options = {}) {
+	const {
+		model = "veo3",
+		duration = 5,
+		aspectRatio = "16:9",
+		maxRetries = 3,
+	} = options;
+
+	const apiKey = process.env.FAL_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"FAL_KEY not configured. Get your key from https://fal.ai/dashboard/keys",
+		);
+	}
+
+	const { fal } = await import("@fal-ai/client");
+	fal.config({ credentials: apiKey });
+
+	const endpoint = model === "veo3-fast" ? "fal-ai/veo3-fast" : "fal-ai/veo3";
+
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const result = await fal.subscribe(endpoint, {
+				input: {
+					prompt: prompt,
+					duration: Math.min(duration, 10),
+					aspect_ratio: aspectRatio,
+				},
+				logs: false,
+			});
+
+			if (result.video?.url) {
+				const videoResponse = await fetch(result.video.url);
+				const videoBuffer = await videoResponse.arrayBuffer();
+				const base64Data = Buffer.from(videoBuffer).toString("base64");
+
+				return {
+					data: base64Data,
+					url: result.video.url,
+					mimeType: "video/mp4",
+					service: "veo3",
+					model: model,
+					cost: PRICING.veo3 * duration,
+					duration: duration,
+				};
+			}
+
+			throw new Error("No video data in Veo 3 response");
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxRetries) {
+				const backoff = Math.pow(2, attempt) * 1000;
+				console.log(
+					`⚠️ Veo 3 attempt ${attempt} failed: ${error.message}. Retrying in ${backoff / 1000}s...`,
+				);
+				await sleep(backoff);
+			}
+		}
+	}
+
+	throw lastError;
+}
+
+/**
+ * Download image from URL and return buffer
+ *
+ * @param {string} url - Image URL
+ * @returns {Promise<Buffer>} Image buffer
+ */
+export async function downloadImage(url) {
+	const response = await fetch(url);
+
+	if (!response.ok) {
+		throw new Error(`Failed to download image: ${response.status}`);
+	}
+
+	const arrayBuffer = await response.arrayBuffer();
+	return Buffer.from(arrayBuffer);
+}
+
+/**
+ * Generate image using auto-selected service
+ * Automatically selects best available service based on preferences
+ *
+ * @param {string} prompt - Image description
+ * @param {Object} options - Generation options
+ * @param {string} options.preferredService - Preferred service
+ * @param {string} options.type - Image type for optimization (hero, illustration, diagram)
+ * @returns {Promise<Object>} Generated image data with buffer
+ */
+export async function generateImage(prompt, options = {}) {
+	const { preferredService, type = "general", ...serviceOptions } = options;
+
+	// If a model is explicitly specified, use it as the service
+	// This allows --service=fal --model=nano-banana-pro to work correctly
+	let service;
+	if (serviceOptions.model && FLUX2_MODELS[serviceOptions.model]) {
+		service = serviceOptions.model;
+	} else {
+		// Select service normally
+		const defaultService = process.env.VISUAL_DEFAULT_SERVICE || "gemini";
+		service = selectBestService(preferredService || defaultService);
+	}
+
+	const modelInfo = serviceOptions.model
+		? ` ${serviceOptions.model}`
+		: ` ${service}`;
+	console.log(`🎨 Generating ${type} image using${modelInfo}...`);
+
+	// Enhance prompt based on image type
+	const enhancedPrompt = enhancePrompt(prompt, type);
+
+	// Generate based on service
+	let result;
+	switch (service) {
+		case "gemini":
+			result = await generateImageGemini(enhancedPrompt, serviceOptions);
+			break;
+
+		case "imagen":
+			result = await generateImageImagen(enhancedPrompt, serviceOptions);
+			break;
+
+		// OpenAI GPT Image models (SOTA)
+		case "gpt-image-1.5":
+		case "gpt-image-1":
+		case "gpt-image-1-mini":
+			result = await generateImageOpenAI(enhancedPrompt, {
+				...serviceOptions,
+				model: service,
+			});
+			break;
+
+		case "flux2-pro":
+		case "flux2-flex":
+		case "flux2-dev":
+			result = await generateImageFlux2(enhancedPrompt, {
+				...serviceOptions,
+				model: service,
+			});
+			break;
+
+		case "flux":
+		case "flux-pro":
+		case "flux-dev":
+		case "nano-banana-pro":
+			result = await generateImageFal(enhancedPrompt, {
+				...serviceOptions,
+				model: serviceOptions.model || service,
+			});
+			break;
+
+		default:
+			throw new Error(`Unknown service: ${service}`);
+	}
+
+	// Convert to buffer
+	let buffer;
+	if (result.data) {
+		buffer = Buffer.from(result.data, "base64");
+	} else if (result.url) {
+		buffer = await downloadImage(result.url);
+	} else {
+		throw new Error("No image data or URL in response");
+	}
+
+	return {
+		...result,
+		buffer,
+		prompt: enhancedPrompt,
+		originalPrompt: prompt,
+	};
+}
+
+/**
+ * Generate video using auto-selected service
+ *
+ * @param {string} prompt - Video description
+ * @param {Object} options - Generation options
+ * @returns {Promise<Object>} Generated video data
+ */
+export async function generateVideo(prompt, options = {}) {
+	const { preferredService = "veo3", ...serviceOptions } = options;
+
+	console.log(`🎬 Generating video using ${preferredService}...`);
+
+	return await generateVideoVeo3(prompt, serviceOptions);
+}
+
+/**
+ * Enhance prompt based on image type
+ *
+ * @param {string} prompt - Original prompt
+ * @param {string} type - Image type (hero, illustration, diagram, infographic-*, etc.)
+ * @returns {string} Enhanced prompt
+ */
+function enhancePrompt(prompt, type) {
+  const enhancements = {
+    // Standard types
+    hero: 'Professional hero image, high quality, visually striking, suitable for article header:',
+    illustration: 'Clean illustration, professional style, clear and informative:',
+    diagram: 'Technical diagram, clear labels, professional design, easy to understand:',
+    screenshot: 'Professional screenshot, clean interface, high resolution:',
+
+    // Infographic types (optimized for GPT Image 1.5 text rendering)
+    'infographic-data': 'Clean data visualization infographic with clear large typography, color-coded sections, modern flat design. Include prominent title area, 3-5 data callouts with large numbers, clean minimal layout, professional business style:',
+    'infographic-process': 'Step-by-step process infographic with clearly numbered steps, simple icons for each step, connecting arrows between steps, clean modern design, horizontal or vertical flow layout, each step clearly labeled with action text:',
+    'infographic-comparison': 'Side-by-side comparison infographic with two distinct columns, clear header labels, aligned comparison points, checkmarks for advantages, X marks for disadvantages, professional business style, easy to scan layout:',
+    'infographic-timeline': 'Horizontal timeline infographic with dated milestone markers, small icons at each event point, connecting timeline line, clean modern design, clear date labels, brief event descriptions:',
+
+    // Technical diagram types
+    'architecture-diagram': 'Technical system architecture diagram with labeled component boxes, directional connection arrows, cloud/server/database icons where appropriate, clear legend area, isometric or clean flat technical illustration style:',
+    'flowchart': 'Professional flowchart with standard shapes - diamonds for decisions, rectangles for processes, ovals for start/end points, clear yes/no branching paths, labeled arrows, clean professional style:',
+    'sequence-diagram': 'Technical sequence diagram showing component interactions with participant boxes at top, vertical lifelines, horizontal arrows with action labels, activation boxes, clean UML-style presentation:',
+
+    // Default
+    general: 'High quality image, professional style:'
+  };
+
+  const prefix = enhancements[type] || enhancements.general;
+  return `${prefix} ${prompt}`;
+}
+
+/**
+ * Get recommended service for image type
+ * Uses user's configured default service if available, otherwise falls back
+ * to first available service. Both Gemini and GPT Image 1.5 are excellent
+ * for text rendering - let the user choose based on their preference.
+ *
+ * @param {string} type - Image type (used for logging/future enhancements)
+ * @param {Array} availableServices - Optional pre-computed available services
+ * @returns {string} Recommended service name
+ */
+export function getRecommendedServiceForType(type, availableServices = null) {
+  // Get available services if not provided
+  if (!availableServices) {
+    const validation = validateAPIKeys();
+    availableServices = validation.availableServices;
+  }
+
+  // Get user's configured default service
+  const userDefault = process.env.VISUAL_DEFAULT_SERVICE;
+
+  // If user has a configured default and it's available, use it
+  if (userDefault && availableServices.includes(userDefault)) {
+    return userDefault;
+  }
+
+  // Otherwise return first available service
+  if (availableServices.length > 0) {
+    return availableServices[0];
+  }
+
+  // Fallback (will likely fail without API keys, but maintains API compatibility)
+  return 'gemini';
+}
+
+/**
+ * Build structured infographic prompt from data
+ *
+ * @param {Object} config - Infographic configuration
+ * @param {string} config.type - Infographic type
+ * @param {string} config.title - Infographic title
+ * @param {Array} config.data - Data points or steps
+ * @param {string} config.style - Style preference
+ * @returns {string} Structured prompt
+ */
+export function buildInfographicPrompt(config) {
+  const { type, title, data = [], style = 'modern flat design' } = config;
+  
+  let prompt = '';
+  
+  switch (type) {
+    case 'infographic-data':
+      prompt = `Data visualization infographic titled "${title}". `;
+      prompt += `Display these metrics prominently: `;
+      prompt += data.map(d => `${d.label}: ${d.value}`).join(', ') + '. ';
+      prompt += `Style: ${style}, clear typography, color-coded sections.`;
+      break;
+      
+    case 'infographic-process':
+      prompt = `Process flow infographic titled "${title}". `;
+      prompt += `Show these steps in sequence: `;
+      prompt += data.map((step, i) => `Step ${i + 1}: ${step}`).join('; ') + '. ';
+      prompt += `Style: numbered steps with icons, connecting arrows, ${style}.`;
+      break;
+      
+    case 'infographic-comparison':
+      prompt = `Comparison infographic titled "${title}". `;
+      prompt += `Compare these aspects: `;
+      prompt += data.map(d => `${d.category} - Option A: ${d.optionA}, Option B: ${d.optionB}`).join('; ') + '. ';
+      prompt += `Style: two-column layout, checkmarks for strengths, ${style}.`;
+      break;
+      
+    case 'infographic-timeline':
+      prompt = `Timeline infographic titled "${title}". `;
+      prompt += `Show these milestones: `;
+      prompt += data.map(d => `${d.date}: ${d.event}`).join('; ') + '. ';
+      prompt += `Style: horizontal timeline, dated markers, ${style}.`;
+      break;
+      
+    default:
+      prompt = `Infographic: ${title}. ${data.join(', ')}. Style: ${style}.`;
+  }
+  
+  return prompt;
+}
+
+/**
+ * Build structured architecture diagram prompt
+ *
+ * @param {Object} config - Diagram configuration
+ * @param {string} config.title - Diagram title
+ * @param {Array} config.components - System components
+ * @param {Array} config.connections - Component connections
+ * @param {string} config.style - Style preference
+ * @returns {string} Structured prompt
+ */
+export function buildArchitectureDiagramPrompt(config) {
+  const { title, components = [], connections = [], style = 'isometric technical' } = config;
+  
+  let prompt = `Technical architecture diagram: "${title}". `;
+  prompt += `Components: ${components.join(', ')}. `;
+  prompt += `Connections: ${connections.join('; ')}. `;
+  prompt += `Style: ${style}, labeled boxes, directional arrows, clean professional design.`;
+  
+  return prompt;
+}
+
+/**
+ * Sleep utility for retry backoff
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Get service information
+ *
+ * @param {string} service - Service name
+ * @returns {Object} Service information
+ */
+export function getServiceInfo(service) {
+	const info = {
+		gemini: {
+			name: "Gemini 3.0 Pro Image",
+			nickname: "Nano Banana",
+			speed: "Fast",
+			cost: "$0.02/image",
+			quality: "Good",
+			bestFor: "Quick hero images, high volume",
+			provider: "Google Gemini API (API Key)",
+			model: GEMINI_IMAGE_MODEL,
+		},
+		imagen: {
+			name: "Imagen 3",
+			nickname: "Premium Quality",
+			speed: "Medium",
+			cost: "$0.03/image",
+			quality: "Excellent",
+			bestFor: "Premium hero images, photorealistic",
+			provider: "Google Gemini API (API Key)",
+			model: GEMINI_IMAGEN_MODEL,
+		},
+		// OpenAI GPT Image Models (SOTA)
+		"gpt-image-1.5": {
+			name: "GPT Image 1.5",
+			nickname: "State-of-the-Art",
+			speed: "Medium",
+			cost: "$0.02-$0.19/image",
+			quality: "Outstanding",
+			bestFor: "Best text rendering, highest quality, transparent backgrounds",
+			provider: "OpenAI",
+			model: "gpt-image-1.5",
+			features: [
+				"Best-in-class text rendering",
+				"Transparency support",
+				"Multiple quality tiers",
+				"WebP/JPEG/PNG output",
+			],
+			qualityTiers: {
+				low: "$0.02/image (~272 tokens)",
+				medium: "$0.07/image (~1056 tokens)",
+				high: "$0.19/image (~4160 tokens)",
+			},
+		},
+		"gpt-image-1": {
+			name: "GPT Image 1",
+			nickname: "Premium Quality",
+			speed: "Medium",
+			cost: "$0.19/image",
+			quality: "Outstanding",
+			bestFor: "High quality images, text rendering",
+			provider: "OpenAI",
+			model: "gpt-image-1",
+			features: [
+				"Excellent text rendering",
+				"Multiple sizes",
+				"Transparency support",
+			],
+		},
+		"gpt-image-1-mini": {
+			name: "GPT Image 1 Mini",
+			nickname: "Cost-Effective",
+			speed: "Fast",
+			cost: "$0.02/image",
+			quality: "Good",
+			bestFor: "Quick images, budget-conscious, high volume",
+			provider: "OpenAI",
+			model: "gpt-image-1-mini",
+			features: ["Fast generation", "Low cost", "Good quality"],
+		},
+		"flux2-pro": {
+			name: "FLUX 2 Pro",
+			nickname: "State-of-the-Art",
+			speed: "Fast",
+			cost: "$0.05/image",
+			quality: "Outstanding",
+			bestFor: "Best quality, fastest generation, lowest cost",
+			provider: "Black Forest Labs (Fal.ai)",
+			model: "flux-2/pro",
+			features: [
+				"Multi-reference (up to 10 images)",
+				"Enhanced photorealism",
+				"Complex typography",
+				"UI mockups",
+			],
+		},
+		"flux2-flex": {
+			name: "FLUX 2 Flex",
+			nickname: "Developer Control",
+			speed: "Medium",
+			cost: "$0.04/image",
+			quality: "Outstanding",
+			bestFor: "Custom parameters, fine-tuned control",
+			provider: "Black Forest Labs (Fal.ai)",
+			model: "flux-2/flex",
+			features: [
+				"Custom inference steps",
+				"Guidance scale control",
+				"Developer-friendly",
+			],
+		},
+		"flux2-dev": {
+			name: "FLUX 2 Dev",
+			nickname: "Open-Weight",
+			speed: "Fast",
+			cost: "$0.025/image",
+			quality: "Excellent",
+			bestFor: "Developer workflows, local deployment option",
+			provider: "Black Forest Labs (Fal.ai)",
+			model: "flux-2/dev",
+			features: [
+				"32B parameters",
+				"Open-weight model",
+				"Local deployment available",
+			],
+		},
+		"flux-pro": {
+			name: "FLUX Pro v1.1 Ultra",
+			nickname: "Legacy Premium",
+			speed: "Medium",
+			cost: "$0.06/image",
+			quality: "Outstanding",
+			bestFor: "Premium artistic images (legacy)",
+			provider: "Fal.ai",
+		},
+		"flux-dev": {
+			name: "FLUX Dev",
+			nickname: "Legacy Developer",
+			speed: "Fast",
+			cost: "$0.025/MP",
+			quality: "Excellent",
+			bestFor: "Developer workflows (legacy)",
+			provider: "Fal.ai",
+		},
+		"nano-banana-pro": {
+			name: "Nano Banana Pro",
+			nickname: "Premium Quality",
+			speed: "Fast",
+			cost: "$0.15/image ($0.30 for 4K)",
+			quality: "Excellent",
+			bestFor: "High-quality branded content, detailed illustrations",
+			provider: "Fal.ai",
+		},
+		veo3: {
+			name: "Veo 3",
+			nickname: "Cutting Edge Video",
+			speed: "Slow",
+			cost: "$0.40/second",
+			quality: "Outstanding",
+			bestFor: "Premium video content, latest features",
+			provider: "Google (Fal.ai)",
+		},
+	};
+
+	return info[service] || null;
+}