Building Real-Time Edge & Web Applications with Nano Banana Image and Video Generators

+------------------------------------------------------------------------------------+
|                         DEPLOYMENT TOPOLOGY ARCHITECTURES                          |
+------------------------------------------------------------------------------------+
|                                                                                    |
|  [ PATTERN A: CLIENT-SIDE WebGPU (Zero Server Cost) ]                              |
|  User Browser (Chromium/WebKit) ──► Loads Quantized ONNX Weights (3.2 GB)          |
|                                 ──► Executes Inference via WebGPU / WGSL Shaders   |
|                                 ──► Direct Canvas Rendering (No Network Roundtrip) |
|                                                                                    |
|  [ PATTERN B: DISTRIBUTED CLOUD EDGE WORKERS (High Throughput & Mobile) ]          |
|  Next.js / React Frontend ──► API Gateway / Edge Proxy (Cloudflare / NGINX)        |
|                           ──► Redis Semantic Cache & Token Rate Limiter            |
|                           ──► GPU Worker Cluster (TensorRT / Triton Inference)     |
|                           ──► WebSocket / SSE Stream ──► Real-Time Client Render   |
+------------------------------------------------------------------------------------+

/**
 * nanoBananaClient.ts
 * Enterprise TypeScript SDK for Nano Banana Image & Video Generator
 */

export interface ImageGenerationRequest {
  prompt: string;
  negativePrompt?: string;
  aspectRatio?: '1:1' | '16:9' | '9:16' | '4:5' | '21:9';
  steps?: number; // 4 to 8 steps recommended
  cfgScale?: number; // 3.0 to 5.0
  seed?: number;
  enableSafetyFilter?: boolean;
}

export interface VideoGenerationRequest extends ImageGenerationRequest {
  durationSeconds?: 4 | 8 | 12;
  motionScale?: number; // 0.1 to 1.0
  cameraTrajectory?: 
    | 'dolly_in_slow'
    | 'dolly_out_smooth'
    | 'orbit_360'
    | 'pan_left'
    | 'pan_right'
    | 'crane_down'
    | 'fpv_drone_fast';
  fps?: 24 | 30 | 60;
  keyframeImageUrl?: string; // For Image-to-Video
}

export interface GenerationResponse {
  jobId: string;
  status: 'completed' | 'failed' | 'processing';
  mediaUrl: string;
  inferenceTimeMs: number;
  seed: number;
  metadata: {
    model: string;
    stepCount: number;
    resolution: string;
  };
}

export class NanoBananaClient {
  private readonly baseUrl: string;
  private readonly apiKey: string;

  constructor(apiKey: string, baseUrl: string = 'https://api.nanobanana.internal/v1') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  /**
   * Generates a photorealistic static image with sub-500ms latency.
   */
  async generateImage(params: ImageGenerationRequest): Promise<GenerationResponse> {
    const response = await fetch(`${this.baseUrl}/images/generate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
      },
      body: JSON.stringify({
        prompt: params.prompt,
        negative_prompt: params.negativePrompt || 'blurry, low quality, deformed anatomy',
        aspect_ratio: params.aspectRatio || '1:1',
        steps: params.steps ?? 6,
        cfg_scale: params.cfgScale ?? 3.8,
        seed: params.seed ?? Math.floor(Math.random() * 10000000),
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Nano Banana Image API Error [${response.status}]: ${errorText}`);
    }

    return (await response.json()) as GenerationResponse;
  }

  /**
   * Generates a temporally coherent video clip with camera trajectory.
   */
  async generateVideo(params: VideoGenerationRequest): Promise<GenerationResponse> {
    const formattedPrompt = params.cameraTrajectory 
      ? `${params.prompt} [camera:${params.cameraTrajectory}] [motion_scale:${params.motionScale ?? 0.5}]`
      : params.prompt;

    const response = await fetch(`${this.baseUrl}/videos/generate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
      },
      body: JSON.stringify({
        prompt: formattedPrompt,
        negative_prompt: params.negativePrompt,
        duration: params.durationSeconds || 4,
        fps: params.fps || 30,
        keyframe_image_url: params.keyframeImageUrl,
        seed: params.seed ?? Math.floor(Math.random() * 10000000),
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Nano Banana Video API Error [${response.status}]: ${errorText}`);
    }

    return (await response.json()) as GenerationResponse;
  }
}

/**
 * useRealtimeNanoBananaStream.ts
 * React Hook for Progressive Video Latent Streaming
 */

import { useState, useEffect, useRef } from 'react';

export function useRealtimeNanoBananaStream(wsUrl: string) {
  const [progress, setProgress] = useState<number>(0);
  const [currentFrameUrl, setCurrentFrameUrl] = useState<string | null>(null);
  const [finalVideoUrl, setFinalVideoUrl] = useState<string | null>(null);
  const [isGenerating, setIsGenerating] = useState<boolean>(false);
  const socketRef = useRef<WebSocket | null>(null);

  useEffect(() => {
    return () => {
      socketRef.current?.close();
    };
  }, []);

  const startStreamGeneration = (prompt: string, cameraTrajectory: string) => {
    setIsGenerating(true);
    setProgress(0);
    setFinalVideoUrl(null);

    const ws = new WebSocket(wsUrl);
    socketRef.current = ws;

    ws.onopen = () => {
      ws.send(JSON.stringify({
        action: 'GENERATE_VIDEO_STREAM',
        prompt,
        camera: cameraTrajectory,
        steps: 8,
      }));
    };

    ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);

      if (msg.type === 'LATENT_FRAME_PREVIEW') {
        // Render base64 low-res preview frame onto UI canvas
        setCurrentFrameUrl(`data:image/jpeg;base64,${msg.payload.base64Jpeg}`);
        setProgress(msg.payload.progressPercentage);
      }

      if (msg.type === 'GENERATION_COMPLETE') {
        setFinalVideoUrl(msg.payload.videoUrl);
        setIsGenerating(false);
        ws.close();
      }
    };

    ws.onerror = (err) => {
      console.error('WebSocket Error in Nano Banana Stream:', err);
      setIsGenerating(false);
    };
  };

  return {
    startStreamGeneration,
    progress,
    currentFrameUrl,
    finalVideoUrl,
    isGenerating,
  };
}

/**
 * server/routes/nanoBananaRoute.ts
 * Express proxy route with validation and Redis caching
 */

import express, { Request, Response } from 'express';
import crypto from 'crypto';

const router = express.Router();

router.post('/api/nano-banana/generate', async (req: Request, res: Response) => {
  try {
    const { prompt, type = 'image', seed, aspectRatio } = req.body;

    if (!prompt || typeof prompt !== 'string') {
      return res.status(400).json({ error: 'Prompt is required and must be a valid string.' });
    }

    // Generate deterministic cache key
    const cacheHash = crypto
      .createHash('sha256')
      .update(`${prompt}-${type}-${seed || 'auto'}-${aspectRatio || '1:1'}`)
      .digest('hex');

    // Call underlying Nano Banana engine
    const upstreamUrl = type === 'video' 
      ? 'http://gpu-worker-cluster.internal:8000/v1/videos/generate'
      : 'http://gpu-worker-cluster.internal:8000/v1/images/generate';

    const gpuResponse = await fetch(upstreamUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Internal-Secret': process.env.NANO_BANANA_INTERNAL_KEY || '',
      },
      body: JSON.stringify(req.body),
    });

    if (!gpuResponse.ok) {
      const err = await gpuResponse.text();
      return res.status(gpuResponse.status).json({ error: err });
    }

    const data = await gpuResponse.json();
    return res.json({ success: true, data, cacheKey: cacheHash });
  } catch (error: any) {
    return res.status(500).json({ error: error.message || 'Internal generation server failure.' });
  }
});

export default router;

   CacheKey = SHA256(Prompt + NegativePrompt + AspectRatio + Seed + Steps)

+------------------------------------------------------------------------------------+
|                         3-TIER CONTENT SAFETY PIPELINE                             |
+------------------------------------------------------------------------------------+
|  [ 1. Ingestion Text Filter ]   ──► Blocks banned keywords and toxic regex         |
|  [ 2. Safe Latent Guidance ]    ──► Steers diffusion latents away from NSFW space   |
|  [ 3. Post-Render Visual Scan ] ──► Lightweight ResNet classifier checks image buffer|
+------------------------------------------------------------------------------------+

/**
 * webgpuPipeline.js
 * In-browser WebGPU inference harness for Nano Banana
 */

async function initWebGPUNanoBanana() {
  if (!navigator.gpu) {
    throw new Error("WebGPU is not supported on this browser.");
  }

  const adapter = await navigator.gpu.requestAdapter({
    powerPreference: "high-performance"
  });
  const device = await adapter.requestDevice();

  console.log("WebGPU Device Initialized:", adapter.info);

  // Load quantized model weights from browser Cache Storage
  const weightsBuffer = await fetchModelWeights('/models/nano_banana_q8.onnx');
  
  // Create Tensor buffers on GPU VRAM
  const latentBuffer = device.createBuffer({
    size: 4 * 64 * 64 * 4, // 4-channel 64x64 latent tensor
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
  });

  return { device, latentBuffer };
}