Skip to main content
Glama
twofxz

google-flow

by twofxz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🎨 flow-py: Google Flow for AI Agents (google-flow-api)

The Unofficial Multi-Agent Automation Engine, CLI, MCP Server & Universal Skill for Google Flow.
Offload production-grade image generation (Nano Banana 2, Nano Banana Pro, Imagen 3) and cinematic video generation (Gemini Omni Flash 1.1) to Google Flow directly from any AI Agent — with zero token waste and native original quality.

License: MIT Python: >=3.10 MCP Ready Universal Skill Security Policy

🤖 Multi-Agent Compatibility Matrix

google-flow-api is built from the ground up to integrate natively into every major AI coding and automation agent:

Agent / Harness

Integration Mechanism

Configuration File

Claude Code (Anthropic)

Native CLI / CLAUDE.md

CLAUDE.md

OpenAI Codex

Subprocess CLI / AGENTS.md

AGENTS.md

OpenClaw

Autonomous Skill Runner

SKILL.md

Hermes Agent (Nous Research)

CLI --json Envelopes

SKILL.md

OpenCode

Skill / MCP Stdio Server

AGENTS.md / google-flow mcp

Google Antigravity

Native Workspace Skill

~/.gemini/config/skills/google-flow/

Cursor / Windsurf / Claude Desktop

Model Context Protocol (MCP)

claude_desktop_config.json

Related MCP server: Google Flow Browser MCP

✨ Key Capabilities

  • 🤫 Silent Background Engine (Headless-by-Default): Operates 100% invisibly in the background with zero window popups (parity with /notebooklm). Chrome runs in --headless=new with Full HD viewport and WebGL acceleration. Use --head whenever you want visual inspection.

  • ⚡ Sub-Second Preflight Auth Check (auth-check): Instantly verifies authenticated state and canvas readiness in sub-second JSON response without opening windows.

  • 🛑 Safe Lifecycle Control (google-flow stop): Safely shuts down the background headless browser daemon and frees RAM/CPU, isolating port 9222 and never touching your personal browsing windows.

  • 🎯 Deterministic JSON Output (--json): All automated commands output structured JSON to stdout with predictable exit codes (0 for success, 1 for error).

  • 👤 Multi-Reference Character Consistency: Pass reference images (front, side, profile) to maintain character facial identity across different scenes.

  • 🎬 Native Video Support (Gemini Omni Flash 1.1): Text-to-Video and Image-to-Video with strictly validated durations (4s, 6s, 8s, 10s) and native 720p MP4 download.

  • 🔄 Concurrent Batch & Carousels (batch): Dispatches multi-slide prompts with a 3-second interval, generating 8-10 slides in parallel in ~1 minute.

  • 🔌 OpenAI-Compatible REST API (google-flow serve): Local FastAPI endpoint emulating POST /v1/images/generations for n8n, Dify, LangChain, or custom applications.

  • 💎 Dual-Detection Asset Downloader: Extracts full 1K/2K resolution images directly from the WebGL canvas and network responses.

📦 Installation & Quickstart

Prerequisites

  • Python 3.10+

  • Google Chrome installed locally

  • uv (recommended) or pip

# Clone repository
git clone https://github.com/twofxz/flow-py.git
cd flow-py

# Install dependencies and dev tools
uv sync --extra dev

🔐 One-Time Authentication

Authenticate your Google account once in a dedicated, isolated browser profile:

uv run google-flow login

  1. A Chrome window opens at https://flow.google.com.

  2. Sign into your Google account and accept terms of service if visiting for the first time.

  3. Press [ENTER] in the terminal when you see the Flow canvas.

  4. Your authenticated session is permanently stored in ~/.google-flow/chrome_profile/ with restricted permissions (0600).

Verify Authentication State

uv run google-flow auth-check --json
{
  "authenticated": true,
  "status": "ready",
  "url": "https://flow.google.com/project/01caca8b-...",
  "session": "default",
  "profile_dir": "C:\\Users\\...\\.google-flow\\chrome_profile"
}

💻 CLI Commands & Recipes

1. Text-to-Image (T2I)

uv run google-flow generate \
  --prompt "Cinematic photo of an astronaut discovering ancient ruins on Mars, volumetric light, 8k" \
  --model "Nano Banana 2" \
  --ratio "16:9" \
  --resolution "1K" \
  --output-dir "./output" \
  --filename "mars_ruins.jpeg"

2. Image-to-Image & Character Consistency (I2I)

uv run google-flow generate \
  --prompt "The character in casual clothing having a coffee in a vibrant Parisian cafe" \
  --reference "./assets/character_face.jpeg" \
  --model "Nano Banana 2" \
  --ratio "9:16" \
  --output-dir "./output" \
  --filename "character_paris.jpeg"

3. Video Generation (Gemini Omni Flash 1.1)

# Text-to-Video (T2V) - 6 seconds
uv run google-flow video \
  --prompt "Cinematic aerial tracking shot orbiting a lighthouse during a storm, rough waves crashing" \
  --duration 6 \
  --ratio "16:9" \
  --output-dir "./output" \
  --filename "stormy_lighthouse.mp4"

# Image-to-Video (I2V) - 4 seconds
uv run google-flow video \
  --prompt "The character smiles gently and turns their head towards the camera" \
  --reference "./output/mars_ruins.jpeg" \
  --duration 4 \
  --ratio "16:9" \
  --output-dir "./output"

4. Batch Carousel Generation (Instagram / LinkedIn)

uv run google-flow batch \
  --manifest "./carousel_prompts.json" \
  --reference "./assets/spokesperson.jpeg" \
  --ratio "3:4" \
  --delay 3.0 \
  --output-dir "./output/carousel"

🔌 Model Context Protocol (MCP) Setup

Connect Google Flow directly to Claude Desktop, Cursor, OpenCode, or Windsurf:

uv run google-flow mcp

Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "google-flow": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/google-flow-api", "google-flow", "mcp"]
    }
  }
}

🐍 Python SDK Usage

from flow_api import FlowClient, FlowEditor, FlowDownloader

client = FlowClient(download_dir="./output_images", headless=True)
try:
    client.start_browser_if_needed()
    page = client.connect()
    client.ensure_canvas()

    editor = FlowEditor(page)
    editor.submit_prompt(
        prompt="Cyberpunk flying taxi soaring between holographic skyscrapers, heavy rain",
        model="Nano Banana 2",
        aspect_ratio="16:9"
    )
    editor.wait_for_generation(timeout=90)

    downloader = FlowDownloader(page, client.download_dir)
    saved_path = downloader.download_current(resolution="1K")
    print(f"✅ Image saved: {saved_path}")
finally:
    client.close()

🌐 OpenAI-Compatible Server (for n8n, Dify, LangChain)

uv run google-flow serve --port 8000

Send standard OpenAI image generation requests:

curl http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Futuristic electric supercar on a scenic coastal highway at sunset",
    "size": "1792x1024"
  }'

🧪 Testing

Run the automated test suite:

uv run pytest

🛡️ Security & Privacy

google-flow-api strictly isolates credentials in ~/.google-flow/ and contains zero telemetry or third-party relays. For detailed security guidelines, threat modeling, and CI/CD best practices, please read SECURITY.md.

📄 License

MIT License - Copyright (c) 2026 Gabriel Siqueira.

Disclaimer: This is an independent open-source automation engine for research and automation purposes. It is not affiliated with, endorsed by, or sponsored by Google.

Available Tools

3 tools
flow_statusA

Verifica o status da conexão com o Google Flow, autenticação da conta e projeto ativo.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It states the action (checking status) which strongly implies a read-only, non-destructive operation, but it does not explicitly confirm the absence of side effects, mention any required permissions, or note rate limits. For a status check this is adequate but not fully explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that immediately conveys the verb and object. Every word adds value, and there is no redundant or filler content. It is as concise as possible while remaining clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple status-check tool with no parameters and an existing output schema, the description covers everything an agent needs to know to call it correctly. The only minor gap is the absence of explicit usage timing, but that is already addressed under usage guidelines and is not critical for a tool this straightforward.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema documents this fully (coverage 100%). No parameter descriptions are needed, and the description correctly avoids adding irrelevant information. The baseline of 4 for no parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (verifica = checks) and a precise resource: connection status, account authentication, and active project. This unambiguously identifies what the tool does and clearly distinguishes it from the sibling generation tools, which produce content rather than report state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a diagnostic purpose but does not explicitly instruct when to call it (e.g., before using generate_image/generate_video) or when not to use alternatives. The context of sibling generation tools makes the intended use apparent, but the text leaves the guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageA

Gera uma imagem cinematográfica de alta qualidade no Google Flow e salva localmente em resolução nativa original (1K/2K).

Args: prompt: Descrição visual detalhada da cena. ratio: Proporção da imagem ('16:9', '9:16', '1:1', '3:4', '4:3'). model: Modelo ('Nano Banana 2' ou 'Nano Banana Pro'). reference_image: Caminho local de imagem de referência para consistência de personagem/estilo. resolution: Resolução nativa ('1K' ou '2K').

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoNano Banana 2
ratioNo16:9
promptYes
resolutionNo1K
reference_imageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the image is 'salva localmente' (saved locally) and mentions native resolution, but it does not disclose potential side effects (e.g., file overwriting), authentication requirements, rate limits, or the nature of the returned result. The 'saves locally' is a meaningful behavior, but coverage is incomplete for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single purpose sentence followed by a parameter list. It is front-loaded with the core action and output behavior, and the parameter list is directly relevant. There is no redundant or filler text. It could be slightly tighter by merging the parameter descriptions with the schema, but it remains concise and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, 1 required, and an output schema exists (though not shown). The description covers the main purpose and parameter values but does not explain what the tool returns (beyond saving locally), any prerequisites (e.g., access to Google Flow), or failure modes. Given the output schema exists, return details might be covered there, but the description alone leaves gaps about the actual output format and any side effects beyond file saving.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description is the sole source of parameter meaning. It explicitly enumerates allowed values for ratio ('16:9', '9:16', '1:1', '3:4', '4:3'), model ('Nano Banana 2' or 'Nano Banana Pro'), and resolution ('1K' or '2K'), which the schema does not provide as enums. It also describes prompt as 'Descrição visual detalhada da cena' and reference_image as a local path for character/style consistency, adding meaning beyond the schema's bare titles and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Gera' (generates), the resource 'imagem cinematográfica de alta qualidade' (high-quality cinematic image), and the context 'no Google Flow' (in Google Flow). It also specifies that the image is saved locally at native resolution. This unambiguously distinguishes it from the sibling generate_video, which generates video instead of images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to choose this tool over generate_video or flow_status. The description does not mention any conditions, exclusions, or alternative selection criteria. It simply describes what the tool does, leaving the agent to infer that it's for images versus video.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_videoA

Gera um vídeo nativo MP4 no Google Flow usando Gemini Omni Flash 1.1 (Text-to-Video ou Image-to-Video).

Args: prompt: Direção de cena e movimento de câmera do vídeo. duration: Duração OBRIGATÓRIA em segundos. O Google Flow aceita exclusivamente: 4, 6, 8 ou 10. ratio: Proporção do vídeo ('16:9' widescreen ou '9:16' vertical Reels/Stories). reference_image: Caminho local de imagem base para geração Image-to-Video (I2V).

ParametersJSON Schema
NameRequiredDescriptionDefault
ratioNo16:9
promptYes
durationNo
reference_imageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears the full behavioral burden, yet it only reveals the output format, model, and T2V/I2V modes. It does not disclose whether creation is asynchronous, how to retrieve the result, or whether flow_status polling is needed—critical operational behavior for a generation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, leading with a one-sentence purpose followed by a clean Args list. No filler is present, though the inaccurate 'OBRIGATÓRIA' label for duration weakens the otherwise tight structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a video-generation tool this is nearly viable: all four parameters are explained and the purpose is clear. The main gaps are the missing asynchronous/status workflow (despite the flow_status sibling) and the schema mismatch about duration, which prevent it from being complete enough for confident autonomous invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning, and it does: it defines prompt as scene/camera direction, enumerates the accepted duration values, clarifies ratio options, and explains reference_image as a local I2V path. However, it calls duration 'OBRIGATÓRIA' while the schema marks it optional with a default, so its guidance is not fully reliable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening phrase 'Gera um vídeo nativo MP4 no Google Flow usando Gemini Omni Flash 1.1' is a specific verb+resource statement and names the output format and model. It clearly distinguishes this from the generate_image and flow_status siblings by focusing on video generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes it clear that video generation is the tool's job, but it does not explicitly state when to prefer it over generate_image or when to use flow_status afterward. Usage is implied by the tool name and first sentence, not articulated as guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedflow_status
    • First observedgenerate_image
    • First observedgenerate_video
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

flow_status is clearly a connection/auth check, while generate_image and generate_video are distinct media generation operations with no overlap in intent. An agent can confidently separate status verification from content creation.

Naming Consistency3/5

generate_image and generate_video follow a consistent verb_noun pattern, but flow_status breaks the convention by leading with the noun and using a different style. The mixed pattern is readable but not fully uniform.

Tool Count4/5

At 3 tools, the surface is small but appropriately scoped for a focused media generation server. Each tool serves a distinct purpose and there is no bloat, though the set could slightly expand to cover more workflow steps.

Completeness3/5

The core generation capabilities for images and videos are present, and the status check covers connection state. However, there are notable gaps: no way to list, retrieve, cancel, or manage generation jobs/results beyond local saving.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers