Nano Banana Integration

Nano Banana is an AI image generation service used for creating before/after transformation images in the Document Builder.

Architecture

sequenceDiagram
    participant UI as Document Builder
    participant API as Nuxt Server
    participant N8N as N8N Workflow
    participant AI as Vertex AI
    participant Store as Supabase Storage

    UI->>API: POST /api/nano-banana/jobs
    API->>N8N: Webhook (job details)
    API-->>UI: { jobId, status: 'queued' }

    N8N->>Store: Fetch input image
    N8N->>AI: Generate image
    AI-->>N8N: Generated variants
    N8N->>Store: Upload outputs
    N8N->>API: POST /api/nano-banana/callback

    API-->>UI: Realtime update (status: 'succeeded')
    UI->>API: GET variants
    UI->>UI: Display in gallery

Data Model

Three database tables support the integration:

• pip_ai_image_jobs — Job metadata (project, prompt, status, input/output)
• pip_ai_image_variants — Generated image variants per job
• pip_ai_image_messages — Chat history for iterative refinements

API Routes

Route	Method	Purpose
/api/nano-banana/jobs	POST	Create generation job
/api/nano-banana/jobs	GET	List jobs for project
/api/nano-banana/messages	POST	Send refinement message
/api/nano-banana/jobs/[id]/messages	GET	Get chat history
/api/nano-banana/callback	POST	N8N callback

Job Lifecycle

queued → running → succeeded (with variants)
                 → failed (with error message)
                 → canceled

Iterative Refinement

Users can send follow-up messages to refine generated images:

1. Select a variant to refine from
2. Enter a refinement prompt
3. New generation job triggered with chat context
4. New variants returned

Document Builder Integration

Generated images can be inserted as:

• image block — Single generated image
• image_compare block — Before/after comparison with slider or side-by-side layout

Guardrails

Guard	Value
Accepted file types	JPEG, PNG, WebP
Max file size	10 MB
Rate limit	10 jobs/hour per user
Concurrent limit	2 running jobs per project
Timeout	5 minutes (auto-fail)

Configuration

N8N_WEBHOOK_NANO_BANANA_PROCESSOR=https://n8n.example.com/webhook/pip-ai-nano-banana
N8N_NANO_BANANA_SECRET=your-shared-secret