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

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

High-speed Chrome CDP session attachment, headless MV3 Direct API proxying, mathematical Shimmer Fix validation, and pre-flight credit safety locks for Nano Banana 2 image generation & Omni Flash / Veo 3.1 video generation.

✨ Key Features • 🏗️ Architecture • 🚀 Quick Start • 📟 CLI • 🐍 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 (isandbox-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.

• 🛡️ 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 ( 2v), Image-to-Video (i2v frame chaining), 6-DOF camera motion vocabulary (pan, ilt, zoom, orbit), and reference entity tracking (mediaId).

• 🔒 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 (ria-disabled="false").

• 🧹 Canvas Auto-Cleanup:

  • Automatic media URL diffing and deletion of generated cards to prevent workspace clutter and asset collision.

Related MCP server: Google Flow Browser MCP

🏗️ Architecture

`mermaid flowchart TD subgraph Interfaces["💻 Developer Interfaces"] CLI["📟 CLI Toolflow-suite"] SDK["🐍 Python SDKFlowClient / AsyncFlowClient"] MCP["🤖 FastMCP Serverflow_generate_image / video"] end

subgraph Core["⚡ Core Orchestrator"]
    Router["🎯 Unified Routing & Engine Fallback"]
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 --> 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,SDK,MCP interface;
class Router core;
class MV3,Bridge,DirectAPI,CDP,Slate,InContext engine;
class Shimmer,CreditLock,CanvasClean safety;
class ImagePipe,VideoPipe,PostProc pipeline;

`

🚀 Quick Start

1. Installation

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

# Create and activate virtual environment
python -m venv .venv

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

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

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

2. Verify Installation

flow-suite diagnostics

📟 Command Line Interface (CLI)

The low-suite CLI provides powerful commands for image and video generation:

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

System Commands

# Diagnostics & Connectivity Checks
flow-suite diagnostics

# List Google Flow Projects
flow-suite projects

🐍 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:

MCP Server Configuration (claude_desktop_config.json or mcp_config.json)

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

Available MCP Tools:

• flow_generate_image: Generate 16:9 / 4:3 images with Nano Banana 2 and The Shimmer Fix.

• flow_generate_video: Render high-impact videos with Omni Flash / Veo 3.1.

• flow_check_status: Check asynchronous video rendering progress.

• flow_create_project: Create or switch between Google Flow workspaces.

🧩 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 at:

   https://labs.google/fx/tools/flow/project/your-project-id

6. The extension will automatically solve window.grecaptcha.enterprise challenges, intercept Bearer tokens, and communicate with your local Python environment via WebSocket on ws://127.0.0.1:8766.

🧪 Comprehensive Test Suite (446/446 Passed)

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

pytest -v

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

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

🌟 ویژگی‌های منحصربه‌فرد و مزایا:

1. حل قطعی باگ ابروبادی (The Shimmer Fix): گوگل هنگام رندر تصاویر، ابتدا یک فایل تار و بی‌کیفیت نمایش می‌دهد. این پکیج با بررسی انحراف معیار کنتراست ($\sigma \ge 15.0$) و ابعاد، مانع از ذخیره فایل‌های تار شده و دقیقاً خروجی شفاف نهایی را استخراج می‌کند.

2. مدل پیش‌فرض ویدیو ⚡ Omni Flash: تنظیم شده برای تولید ویدیوهای سرعتی و داینامیک با پشتیبانی کامل از ابعاد ۱۶:۹ افقی (یوتیوب و وب‌سایت) و ۹:۱۶ عمودی (ریلز و استوری اینستاگرام).

3. قفل ایمنی کردیت (Credit Safety Lock): جلوگیری از مصرف ناخواسته کردیت‌های گران‌قیمت ویدیو هنگام درخواست‌های تولید تصویر.

4. تایپ خودکار در ادیتور Slate.js: حل مشکل قفل بودن دکمه Create در فلو با شبیه‌سازی دقیق رویدادهای کیبورد.

🧩 راهنمای گام‌به‌گام نصب افزونه اختصاصی کروم (Google Chrome MV3 Extension):

این پلتفرم شامل یک افزونه اختصاصی، سبک و یکپارچه در پوشه extension/ است که نیازی به نصب‌های متعدد ندارد. این افزونه چالش‌های ری‌کپچای گوگل (window.grecaptcha.enterprise) را در پس‌زمینه حل کرده و توکن‌های ورود حساب شما را برای پایتون استخراج می‌کند:

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/project/your-project-id

6. تمام! افزونه با نشان سبز فعال شده و به صورت امن و خودکار پل ارتباطی را با کدهای پایتون و ابزار خط فرمان برقرار می‌کند.

🚀 شروع سریع در ۳ گام:

گام ۱: نصب و فعال‌سازی محیط

git clone https://github.com/omid-io/google-flow-suite.git
cd google-flow-suite
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[all]"

گام ۲: تولید تصویر فوق‌العاده با Nano Banana 2

flow-suite generate "طراحی اتاق کار برنامه‌نویسی مدرن با نورپردازی نئون فیروزه‌ای و جزئیات دقیق" --aspect-ratio 16:9 --style cinematic --output cover.jpg

گام ۳: تولید ویدیو با حرکت زوم دوربین با Omni Flash

flow-suite video "پرواز پرسرعت پهپاد از میان آسمان‌خراش‌های نورانی در شب بارانی" --camera-motion zoom_in --model omni-flash --output drone.mp4

🎨 الگوهای پرامپت طلایی:

۱. کاور مقالات فنی و بنر وب‌سایت (۱۶:۹):

Cinematic 16:9 technical banner for software engineering article. Left side shows an AI chat robot trapped in a glass jar. Center shows an isometric glowing quantum core router labeled 'MCP' emitting radiant cyan fiber-optic data beams connecting outward to a PostgreSQL database, Linux terminal CLI, and file tree. Right side shows autonomous agents working seamlessly. Dramatic volumetric studio lighting, deep slate dark background, bold Persian typography displaying «پروتکل MCP» with glowing cyan accent and subtitle «پل ارتباطی هوش مصنوعی با دنیای واقعی». Clean 8k render, no watermarks.

۲. سناریوی ریلز اینستاگرام با مدل Omni Flash (۹:۱۶):

A cinematic vertical 9:16 drone shot flying smoothly through a luxury modern architectural space with glass walls, water reflections, and warm ambient evening lighting. [Camera: Zoom In] [Model: Omni Flash High Impact]

📄 License

Distributed under the MIT License. See LICENSE for details.

Copyright (c) 2026 Omid Zaferi (omid-io)