Skip to content
BranchesTags

Repository files navigation

🍌 Google Flow Automation Suite (Nano Banana 2 & Omni Flash)

Google Flow Automation Suite Banner

CI Python 3.10+ FastAPI FastMCP Chrome MV3 Playwright Tests License: MIT

The Production-Grade Media Automation Platform & Developer Suite for Google Flow

High-speed Chrome CDP session attachment, headless MV3 Direct API proxying, REST API webhooks, mathematical Shimmer Fix validation, SQLite asset catalog, and 50 golden prompt presets for Nano Banana 2 image generation & Omni Flash / Veo 3.1 video generation.

✨ Key Features • 🏗️ Architecture • 🚀 Quick Start • 📟 CLI • 🌐 REST API & Webhooks • 🎨 Golden Presets • 🐍 Python SDK • 🤖 FastMCP • 🧩 Chrome Extension • 🇮🇷 راهنمای جامع فارسی

✨ Key Features

  • ⚡ Unified Dual-Engine Architecture:
    • Engine A (Direct API Bridge): Chrome MV3 background proxy solving window.grecaptcha.enterprise in-DOM and intercepting Bearer tokens for high-throughput headless batching (aisandbox-pa.googleapis.com).
    • Engine B (Zero-Friction CDP): Attaches directly to your active, logged-in browser session via Playwright without closing Chrome or re-authenticating.
  • 🌐 FastAPI REST API & Webhook Server (flow-suite serve):
    • Instant HTTP bridge for n8n, Telegram bots, and external webhooks with interactive Swagger docs at /docs.
  • 🗄️ SQLite Asset Catalog & History Tracker (flow-suite history):
    • Automatically records generated assets, prompts, models, and metadata into a local flow_catalog.sqlite3 database.
  • 🎨 50 Golden Prompt Presets (flow-suite presets):
    • Curated, production-tested prompt formulas across 5 domains (Software Architecture, Instagram Dynamic Reels, Luxury Salon Aesthetics, 3D Isometric UI, and Typographic Posters).
  • 🛡️ The Shimmer Fix (Contrast StdDev $\sigma \ge 15.0$):
    • 4-stage mathematical validator (Resolution Gate $\ge 1000\text{px}$, File Size $\ge 100\text{KB}$, Grayscale Standard Deviation $\sigma \ge 15.0$, Dynamic Range $\Delta V \ge 100$) preventing premature download of blurry placeholder cards.
  • 🎬 Omni Flash & Veo 3.1 High-Impact Video:
    • Full support for Text-to-Video (t2v), Image-to-Video (i2v frame chaining), 6-DOF camera motion vocabulary (pan, tilt, zoom, orbit), and reference entity tracking (reference_media_id).
  • 🔒 Credit Safety Lock:
    • Pre-flight guard preventing accidental consumption of expensive video credits during image requests.
  • ⌨️ Slate.js Synthetic Typing:
    • Sequential keystroke simulation with micro-delays to reliably activate the React-controlled Create button (aria-disabled="false").
  • 🧹 Canvas Auto-Cleanup:
    • Automatic media URL diffing and deletion of generated cards to prevent workspace clutter and asset collision.

🏗️ Architecture

flowchart TD
    subgraph Interfaces["💻 Developer Interfaces"]
        CLI["📟 CLI Tool<br/><b>flow-suite</b>"]
        REST["🌐 REST API / Webhooks<br/><b>FastAPI (Port 8767)</b>"]
        SDK["🐍 Python SDK<br/><b>FlowClient / AsyncFlowClient</b>"]
        MCP["🤖 FastMCP Server<br/><b>flow_generate_image / video</b>"]
    end

    subgraph Core["⚡ Core Orchestrator"]
        Router["🎯 Unified Routing & Engine Fallback"]
        Catalog["🗄️ SQLite Asset Catalog<br/><b>flow_catalog.sqlite3</b>"]
        Presets["🎨 50 Golden Presets<br/><b>examples/golden_prompts.json</b>"]
    end

    subgraph Engines["🚀 Dual-Engine Execution Layer"]
        subgraph EngineA["Engine A: Direct API Bridge"]
            MV3["🧩 MV3 Chrome Extension<br/>(reCAPTCHA & Bearer Sniffer)"]
            Bridge["🔌 Local JSON-RPC Bridge<br/>(ws://127.0.0.1:8766)"]
            DirectAPI["🌐 aisandbox-pa.googleapis.com<br/>(Direct Batch API)"]
        end

        subgraph EngineB["Engine B: CDP / Browser Driver"]
            CDP["🎮 Playwright CDP Driver<br/>(Attach to Port 9222 / 2360)"]
            Slate["⌨️ Slate.js Synthetic Typer<br/>(Keystroke Simulator)"]
            InContext["📥 In-Context Cookie Fetch<br/>(Preserves Session State)"]
        end
    end

    subgraph Safety["🛡️ Reliability & Safety Guard"]
        Shimmer["🔬 The Shimmer Fix<br/>(Contrast StdDev σ ≥ 15.0 & W ≥ 1000px)"]
        CreditLock["🔒 Credit Safety Lock<br/>(Anti-Burn Video Guard)"]
        CanvasClean["🧹 Canvas State Tracker<br/>(Media Diff & Auto-Cleanup)"]
    end

    subgraph Pipelines["🎬 Media Pipeline & Post-Processing"]
        ImagePipe["🍌 Nano Banana 2<br/>(16:9 / 4:3 Image Pipeline)"]
        VideoPipe["⚡ Omni Flash / Veo 3.1<br/>(6-DOF Camera & i2v Chaining)"]
        PostProc["✨ Progressive JPEG & MP4<br/>(Metadata & Provenance Embedder)"]
    end

    Interfaces --> Router
    Router --> Catalog
    Router --> Presets
    Router --> EngineA
    Router --> EngineB
    MV3 --> Bridge --> DirectAPI
    CDP --> Slate --> InContext
    DirectAPI --> Safety
    InContext --> Safety
    Safety --> Pipelines
    Pipelines --> Output[("📦 Final Verified Assets")]

    classDef interface fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#fff;
    classDef core fill:#0f172a,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef engine fill:#1e1e2e,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef safety fill:#181825,stroke:#22c55e,stroke-width:2px,color:#fff;
    classDef pipeline fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff;

    class CLI,REST,SDK,MCP interface;
    class Router,Catalog,Presets core;
    class MV3,Bridge,DirectAPI,CDP,Slate,InContext engine;
    class Shimmer,CreditLock,CanvasClean safety;
    class ImagePipe,VideoPipe,PostProc pipeline;
Loading

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/omid-io/google-flow-suite.git
cd google-flow-suite

# Create virtual environment
python -m venv .venv

# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

# On Linux/macOS:
# source .venv/bin/activate

# Install with all enterprise dependencies
pip install -e ".[all]"

2. Verify Installation

flow-suite --version
flow-suite diagnostics

📟 Command Line Interface (CLI)

Generate Images (Nano Banana 2)

# 16:9 Landscape Banner with Cinematic Preset
flow-suite generate "A futuristic developer desk with neon cyan fiber optics" --aspect-ratio 16:9 --style cinematic --output banner.jpg

# 4:3 Classical Composition
flow-suite generate "Luxury perfume bottle on Italian marble with morning sunlight" --aspect-ratio 4:3 --output perfume.jpg

Generate High-Impact Videos (Omni Flash / Veo 3.1)

# Text-to-Video with Camera Zoom
flow-suite video "FPV drone racing through neon cyberpunk skyscrapers at night" --camera-motion zoom_in --model omni-flash --output drone.mp4

# Image-to-Video (Chaining from previously generated image)
flow-suite video "Animate water waves and golden reflections" --camera-motion pan_right --reference-media-id media_img_01_a9f8 --output animated.mp4

Generation History & Presets

# View recent generation history from local SQLite catalog
flow-suite history --limit 10

# List golden prompt presets
flow-suite presets

# Filter presets by category (software_engineering, instagram_reels, commercial_luxury_products, isometric_3d_ui, typographic_marketing)
flow-suite presets --category instagram_reels

Start REST API Server

# Launch FastAPI server on port 8767 for n8n & Telegram webhooks
flow-suite serve --port 8767

🌐 REST API & Webhooks (FastAPI)

Start the local server with flow-suite serve and access interactive Swagger documentation at http://127.0.0.1:8767/docs:

Endpoints:

  • POST /v1/images/generate: Generate 16:9 / 4:3 images with Nano Banana 2.
  • POST /v1/videos/generate: Render high-impact dynamic videos with Omni Flash / Veo 3.1.
  • GET /v1/status/{task_id}: Poll asynchronous rendering status.
  • GET /v1/history: Retrieve paginated asset history from SQLite catalog.
  • POST /v1/webhooks/events: Receive external worker callbacks.
  • GET /health: Service health check and author metadata.
# Example curl request to generate an image
curl -X POST "http://127.0.0.1:8767/v1/images/generate"      -H "Content-Type: application/json"      -d '{"prompt": "Isometric quantum core router labeled MCP glowing with cyan lasers", "aspect_ratio": "16:9"}'

🎨 50 Golden Presets Library

The suite includes 50 production-grade prompts in examples/golden_prompts.json across 5 categories:

  1. Software Engineering & Cloud Architecture (16:9): MCP routers, Kubernetes mesh, clean code desks, agent swarms.
  2. Instagram Dynamic Reels & Shorts (9:16 Omni Flash): FPV drone rush, hypercar drift, liquid gold slow-motion, space nebulas.
  3. Commercial Luxury Products & Cosmetics (16:9 Studio): VIP facial suites, keratin silk hair, 24k gold serums, royal bridal hair.
  4. 3D Isometric Futuristic UI & Quantum Systems: Supercomputer racks, glassy fintech dashboards, blockchain nodes.
  5. Typographic Marketing Posters: Bold in-image headline typography in Persian and English with quotes.

🐍 Python SDK

Synchronous Client (FlowClient)

from google_flow_suite import FlowClient

with FlowClient() as client:
    # 1. Generate High-Res Image
    img = client.generate_image(
        prompt="Modern luxury salon interior with dark slate and warm gold accents",
        aspect_ratio="16:9",
        style_preset="cinematic"
    )
    print(f"Image Created: {img.url}")

    # 2. Generate Omni Flash Video
    vid = client.generate_video(
        prompt="Slow motion water droplet falling with crystal ripples",
        camera_motion="zoom_in",
        model="omni-flash"
    )
    print(f"Video Created: {vid.url}")

Asynchronous Client (AsyncFlowClient)

import asyncio
from google_flow_suite import AsyncFlowClient

async def main():
    async with AsyncFlowClient() as client:
        result = await client.generate_image(
            prompt="Isometric server rack glowing with quantum light",
            aspect_ratio="16:9"
        )
        print(f"Asset ID: {result.media_id}")

asyncio.run(main())

🤖 FastMCP Server for AI Agents

Connect Google Flow directly into Antigravity, Claude Desktop, and Cursor using FastMCP:

Configuration (claude_desktop_config.json or mcp_config.json)

{
  "mcpServers": {
    "google-flow-suite": {
      "command": "python",
      "args": ["-m", "google_flow_suite.mcp.server"]
    }
  }
}

🧩 Chrome MV3 Extension Setup

The repository includes a ready-to-load Manifest V3 Chrome extension located in the extension/ directory:

  1. Open Google Chrome and navigate to: 
    chrome://extensions
  2. In the top-right corner, toggle Developer mode to ON.
  3. Click the Load unpacked button in the top-left corner.
  4. Select the extension folder inside this repository (google-flow-suite/extension).
  5. Open Google Flow (https://labs.google/fx/tools/flow).
  6. The extension will automatically solve window.grecaptcha.enterprise challenges and communicate with your local Python environment via WebSocket on ws://127.0.0.1:8766.

🧪 Comprehensive Test Suite (462/462 Passed)

The suite is exhaustively verified across 462 unit, mock, integration, and adversarial stress tests:

pytest -v
Test Tier Focus Area Test Count Status
Tier 1: Units Config, Models, Prompt Compiler, Shimmer Math 96 tests ✅ 100% Passed
Tier 2: Engines CDP Driver Mock, Credit Guard, Direct API Client 16 tests ✅ 100% Passed
Tier 3: Interfaces CLI, FastMCP Server, FastAPI REST Server, Catalog DB, Presets, Python SDK 28 tests ✅ 100% Passed
Tier 4: E2E Pipelines Image, Video, Post-processing Workflows 8 tests ✅ 100% Passed
Tier 5: Adversarial Deep Stress, Lifecycle, Chaos Shimmer, Resilience 314 tests ✅ 100% Passed

🇮🇷 راهنمای جامع فارسی (Iranian Developer Guide)

پروژه Google Flow Automation Suite v0.2.0 یک پلتفرم استاندارد صنعتی و جامع برای اتوماسیون کامل سرویس Google Flow است. این ابزار به توسعه‌دهندگان، تولیدکنندگان محتوا و متخصصان هوش مصنوعی این امکان را می‌دهد که بدون نیاز به کلیک‌های دستی در مرورگر، از قدرتمندترین مدل‌های گوگل یعنی Nano Banana 2 (تولید تصویر با کیفیت خیره‌کننده) و ⚡ Omni Flash / Veo 3.1 (تولید ویدیوهای سینمایی پرتحرک) در کدهای پایتون، خط فرمان (CLI)، سرور وب REST API، پایپ‌لاین‌های n8n، یا از طریق دستیارهای هوش مصنوعی (مانند Claude و Antigravity) استفاده کنند.

🌟 امکانات و قابلیت‌های کلیدی:

  1. 🌐 وب‌سرور REST API و وب‌هوک (flow-suite serve): اتصال مستقیم به n8n، ربات‌های تلگرام و کلاینت‌های شبکه با داکیومنت تعاملی Swagger در http://127.0.0.1:8767/docs.
  2. 🗄️ کاتالوگ دیتابیس لوکال SQLite (flow-suite history): ذخیره خودکار تمام پرامپت‌ها، تصاویر و ویدیوهای رندرشده در دیتابیس flow_catalog.sqlite3.
  3. 🎨 بانک ۵۰ پرامپت طلایی و لایبرری پریست‌ها (flow-suite presets): ۵۰ فرمول تست‌شده در ۵ دسته‌بندی (معماری نرم‌افزار، ریلزهای داینامیک اینستاگرام، عکاسی استودیویی محصولات لوکس، موکاپ‌های سه‌بعدی، پوسترهای متنی فارسی و انگلیسی).
  4. حل قطعی باگ ابروبادی (The Shimmer Fix): بررسی انحراف معیار کنتراست ($\sigma \ge 15.0$) و ابعاد، مانع از ذخیره فایل‌های تار شده و دقیقاً خروجی شفاف نهایی را استخراج می‌کند.
  5. مدل پیش‌فرض ویدیو ⚡ Omni Flash: تنظیم شده برای تولید ویدیوهای سرعتی و داینامیک با پشتیبانی کامل از ابعاد ۱۶:۹ افقی (یوتیوب و وب‌سایت) و ۹:۱۶ عمودی (ریلز و استوری اینستاگرام).
  6. قفل ایمنی کردیت (Credit Safety Lock): جلوگیری از مصرف ناخواسته کردیت‌های گران‌قیمت ویدیو هنگام درخواست‌های تولید تصویر.
  7. 🚀 لانچر ۱-کلیک ویندوز (run_chrome_debug.bat): اجرای فوری کروم در حالت دیباگ بدون نیاز به تایپ دستور در ترمینال.

🧩 راهنمای گام‌به‌گام نصب افزونه اختصاصی کروم:

  1. مرورگر Google Chrome را باز کنید و آدرس chrome://extensions را وارد نمایید.
  2. در گوشه بالا سمت راست، گزینه Developer mode را روشن (ON) کنید.
  3. در گوشه بالا سمت چپ، روی دکمه Load unpacked کلیک کنید.
  4. پوشه extension داخل مخزن این پروژه (google-flow-suite/extension) را انتخاب کنید.
  5. وارد صفحه گوگل فلو شوید (https://labs.google/fx/tools/flow). افزونه با نشان سبز فعال شده و به پایتون متصل می‌گردد.

🚀 دستورات پرکاربرد خط فرمان:

# ۱. تولید عکس ۱۶:۹ با مدل Nano Banana 2
flow-suite generate "طراحی اتاق کار برنامه‌نویسی مدرن با نورپردازی نئون فیروزه‌ای" --aspect-ratio 16:9 --output cover.jpg

# ۲. تولید ویدیو با حرکت زوم دوربین با Omni Flash
flow-suite video "پرواز پرسرعت پهپاد از میان آسمان‌خراش‌های نورانی در شب بارانی" --camera-motion zoom_in --output drone.mp4

# ۳. مشاهده تاریخچه کارهای تولیدشده در دیتابیس SQLite
flow-suite history --limit 10

# ۴. مشاهده و جستجو در لیست ۵۰ پرامپت طلایی
flow-suite presets --category instagram_reels

# ۵. اجرای وب‌سرور محلی برای اتصال به n8n و تلگرام
flow-suite serve --port 8767

📄 License

Distributed under the MIT License. See LICENSE for details.

Crafted with ❤️ by Omid Zaferi (@omid-io)

About

Unified Production-Grade Google Flow Automation Suite (Nano Banana 2 & Omni Flash / Veo 3.1) with Chrome MV3 Bridge, Playwright CDP, FastMCP & CLI

Topics

ai-generationbrowser-automationchrome-extensionfastmcpgoogle-flowmcpnano-banana-2omni-flashplaywrightpythonveovideo-generation

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages