Flow Agent

"a glowing crystal lotus on calm water"  →  🖼️  output/acct-38e6.jpg  (26 s)
"hyper-lapse sunrise over ocean horizon"  →  🎬  output/acct-video.mp4  (58 s)

What does it do?

Flow Agent is a local server and CLI that connects to Google Flow to generate high-quality AI images and videos. You set it up once, and then you can use it three ways:

Features at a Glance

• 🖼️ Text → Image — aspect ratios: 1:1 16:9 9:16 4:3 3:4, up to 4 variations at once
• 🎬 Text → Video — durations: 4s 6s 8s 10s, quality: 360p / 720p
• 🎞️ Image → Video — animate any image into a video clip
• 👥 Multi-Account — add multiple Google accounts to pool credits
• 🔌 OpenAI Compatible — drop-in replacement: change base_url, nothing else
• 📊 History & Stats — every generation logged to local SQLite with credits tracking
• 🩺 Self-Diagnostics — ./bin/flow doctor tells you exactly what to fix

Quick Start

1 — Install

cd flow-agent

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -e '.[test]'

2 — Connect Your Google Account

You need the Flow Chrome Extension installed in Chrome first.
Load it from the flow-extension/ folder via chrome://extensions → Load unpacked.

# Start the WebSocket bridge (keep this running in a terminal)
./bin/flow bridge

Then open https://labs.google/fx/tools/flow in Chrome while signed in to your Google account. The extension will automatically save your session to cookies/.

3 — Verify Setup

./bin/flow doctor

You should see:

ok    version     flow-go 0.1.0
ok    database    data/flow.db
ok    cookies     1 account(s) loaded
ok    browser     extension attached

4 — Generate Your First Image

python main.py image "a glowing crystal lotus on calm water" --aspect 1:1

✓ saved output/acct-38e60406-67b.jpg  (26 s)

Usage

🖼️ Images

# Basic — saves to output/
python main.py image "PROMPT"

# With options
python main.py image "PROMPT" \
  --aspect 16:9          # 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | square | landscape | portrait
  --count 2              # 1–4 variations
  --model narwhal        # narwhal | harbor_seal | gem_pix_2

# Run on all accounts at once (pools credits)
python main.py image "PROMPT" --all

🎬 Videos

# Text to video
python main.py video "PROMPT" \
  --aspect landscape     # landscape | portrait | 16:9 | 9:16
  --duration 8s          # 4s | 6s | 8s | 10s
  --quality 720p         # 360p | 720p

# Image to video (animate a photo)
python main.py video "camera slowly pans right" \
  --start-image output/my-image.jpg

💰 Balance & Stats

python main.py balance            # cached (instant)
python main.py balance --refresh  # live probe from Google Flow

python main.py stats              # generation history + credit usage
python main.py projects           # list your Flow projects

REST API Server

python main.py server --port 8001

Interactive docs open at http://127.0.0.1:8001/docs

All Endpoints

Every /api/v1/* route also has a /v1/* alias — use whichever you prefer.

Quick API Example

curl -X POST http://127.0.0.1:8001/api/v1/image \
  -H "Content-Type: application/json" \
  -d '{"prompt": "neon cyber dragon over misty mountains", "aspect": "16:9"}'

{
  "job_id": "ba884266-...",
  "status": "succeeded",
  "elapsed_seconds": 26.3,
  "files": [
    { "url": "http://127.0.0.1:8001/api/v1/media/acct-38e60406-67b.jpg" }
  ]
}

OpenAI SDK — Drop-in Replacement

Change one line in your existing OpenAI code:

from openai import OpenAI

# ← Change only this line
client = OpenAI(base_url="http://127.0.0.1:8001/v1", api_key="not-needed")

# Everything else stays exactly the same ↓
response = client.images.generate(
    prompt="a cute red origami fox sitting in autumn leaves",
    size="1792x1024",   # → Flow 16:9
    n=1
)
print(response.data[0].url)

Supported OpenAI sizes → Flow mapping:

MCP — Use With Claude / Cursor / AGY

Flow Agent exposes 5 tools via the Model Context Protocol, so your AI assistant can generate images and videos directly for you.

Setup (Claude Desktop)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flow": {
      "command": "python3",
      "args": ["/absolute/path/to/flow-agent/main.py", "mcp"]
    }
  }
}

Setup (Cursor / AGY)

{
  "flow": {
    "command": "python3",
    "args": ["/absolute/path/to/flow-agent/main.py", "mcp"]
  }
}

Available MCP Tools

Now just ask your assistant: "Generate a 16:9 image of a cyberpunk city at dawn using Flow"

Project Structure

flow-agent/
│
├── bin/
│   ├── flow              → auto-selects the right binary
│   ├── flow-macos        → macOS universal binary (arm64 + x86_64)
│   ├── flow-linux        → Linux binary
│   └── flow-windows.exe  → Windows binary
│
├── cookies/
│   └── account_<id>.json → saved Google account sessions
│
├── data/
│   └── flow.db           → SQLite: generation history + credits
│
├── output/
│   └── *.jpg, *.mp4      → your generated images and videos
│
├── flow_agent/
│   ├── api.py            → FastAPI REST server (Native + OpenAI routes)
│   ├── engine.py         → subprocess bridge to bin/flow
│   └── mcp_server.py     → MCP JSON-RPC server
│
├── docs/                 → detailed reference docs
├── tests/                → 77 passing tests
├── main.py               → CLI entrypoint
└── pyproject.toml

Environment Variables

Troubleshooting

Run Tests

python3 -m pytest -q --basetemp=/tmp/fa_test

77 passed in 0.38s

Documentation

License

MIT — free to use, modify, and distribute.