flowfast
Google Flow (Nano Banana, Veo, free 1080p upscale) over plain HTTP: CLI, daemon, MCP server. Built on gflow-cli.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jvanleeuwen4--flowfast)HTML
<a href="/listings/jvanleeuwen4--flowfast"><img src="/api/listings/jvanleeuwen4--flowfast/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requirements: Windows or macOS, Google Chrome, and [uv](https://docs.astral.sh/uv/).
1. **gflow-cli, signed in once.** flowfast uses its signed-in Chrome profile:
uv tool install gflow-cli gflow auth login
2. **flowfast as a command:**
git clone https://github.com/JvanLeeuwen4/flowfast cd flowfast uv tool install --editable . flowfast --version
`--editable` means code changes in this folder take effect without reinstalling. Afterwards `flowfast` works from any folder. Remove it with `uv tool uninstall flowfast`. If downloading a new Playwright is slow, reuse the version gflow-cli already has: `uv tool install --editable . --with playwright==1.61.0`.
On Windows, run this in **your own terminal**, not only inside the Claude desktop app. That app runs as a Windows package and redirects its writes to `%APPDATA%` into its own package folder, so an install made from there may be invisible outside it.
flowfast does not import gflow-cli. It only reads gflow-cli's files to find the profile:
| setting | meaning | |---|---| | `FLOWFAST_PROFILE_DIR` | full path of a Chrome profile to use (wins over everything) | | `FLOWFAST_PROFILE` / `GFLOW_CLI_PROFILE` | profile name | | `default_profile` in gflow-cli's `config.toml` | gflow-cli's default (normally used) | | `GFLOW_CLI_HOME` | gflow-cli home folder, if not the default |
gflow-cli's default home is `%LOCALAPPDATA%\ffroliva\gflow-cli` on Windows, `~/Library/Application Support/gflow-cli` on macOS and `~/.local/share/gflow-cli` on Linux.
**gflow-cli and flowfast cannot use the profile at the same time** (Chrome locks it). Stop the daemon before running gflow-cli, and vice versa.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 519 lines
- # flowfast
- **Google Flow from the command line, over plain HTTP.** Nano Banana images, Veo / Omni video and Flow's **free 1080p video upscale**, as a CLI, a local HTTP daemon, an MCP server and a Python API.
- flowfast is a fast companion to **[gflow-cli](https://github.com/ffroliva/gflow-cli)** by [@ffroliva](https://github.com/ffroliva), and builds on it. gflow-cli drives Flow's web UI with Playwright. flowfast reuses gflow-cli's signed-in browser profile, then sends Flow's own backend RPCs directly. The browser is used for one thing only: minting the reCAPTCHA token each request needs.
- [](LICENSE)
- 
- 
- 
- | one image (nano2-lite, warm) | 24 turnaround views (8 assets × 3) | one video (Veo 3.1 Lite, i2v) | 1080p upscale of a clip |
- |---|---|---|---|
- | gflow-cli 19.8 s → **flowfast 7.8 s** | gflow-cli ~33 min → **flowfast 2 min 38 s** | **~40 s** submit + render + download | **~40 s, 0 credits** |
- > **Unofficial.** flowfast is not affiliated with Google. It uses Flow's private, undocumented web endpoints with *your own* signed-in account, so it is subject to Flow's terms and can break on any Flow deploy (see [When it breaks](#when-it-breaks-compare-with-gflow-cli)). Keep request volume reasonable.
- ---
- ## At a glance (for people and agents)
- * **What:** generate images (text-to-image, image-to-image, 3D turnaround views) and videos (text-to-video, image-to-video), and upscale videos to 1080p, in [Google Flow](https://flow.google.com).
- * **How:** direct `batchexecute` RPCs over `httpx`. There are no clicks and no DOM selectors. One hidden Chrome page mints reCAPTCHA tokens (~0.14 s each when warm).
- * **Builds on:** [gflow-cli](https://github.com/ffroliva/gflow-cli). Its login (`gflow auth login`) provides the browser profile flowfast uses, and its code is the reference for Flow's protocol. flowfast does not import gflow-cli; it only reads gflow-cli's profile folder.
- * **Why faster:** gflow-cli loads the full Flow app, types the prompt and clicks through the UI for every request. flowfast skips the UI. A warm request costs only Google's own render time, and requests run in parallel (8 by default).
- * **Interfaces:** `flowfast` CLI · `flowfast serve` (HTTP on `127.0.0.1:8765`) · `flowfast mcp` (stdio MCP server) · `from flowfast import Engine`.
- * **Cost:** images and the 1080p upscale are free on Flow. **Video generation costs Flow credits** (4–12 per clip on the cheap models).
- * **Tested on** Windows 11 and macOS, with a tier-1 account.
- ## How it differs from gflow-cli
- ```mermaid
- flowchart LR
- subgraph G["gflow-cli: UI automation"]
- direction TB
- g1["your command"] --> g2["Playwright opens Chrome<br/>and loads the full Flow app"]
- g2 --> g3["types the prompt, clicks<br/>Generate, watches the page"]
- g3 --> g4["Flow backend"]
- end
- subgraph F["flowfast: direct RPCs"]
- direction TB
- f1["your command"] --> f2["httpx sends Flow's own<br/>batchexecute RPCs"]
- f1 -.->|"one token per request, ~0.14 s"| f3["one hidden Chrome page<br/>grecaptcha.enterprise.execute()"]
- f3 -.-> f2
- f2 --> f4["Flow backend"]
- end
- P[("gflow-cli's signed-in<br/>Chrome profile")] --> g2
- P --> f3
- ```
- | | gflow-cli | flowfast |
- |---|---|---|
- | Talks to Flow via | the web UI (Playwright: load, type, click) | Flow's backend RPCs over HTTP |
- | Browser work per image | 3 full app loads, typing, clicking | 1 `evaluate` call (**0.14 s**) on an already open page |
- | One image, wall time | 19.8 s | **7.8 s** warm (≈ Google's own ~6.9 s render) |
- | Throughput | ~3 images/min | **44.5 images/min** (8 in parallel) |
- | Breaks when | Flow's UI or protocol changes | Flow's protocol changes (UI changes don't matter) |
- | Feature coverage | broad: images, video, extend, scenes, characters, upscale, … | focused: t2i, i2i, views, t2v, i2v, 1080p video upscale |
- | Login | `gflow auth login` | reuses gflow-cli's profile |
- **Use both.** gflow-cli covers far more of Flow and is the reference when the protocol changes. flowfast is for the hot path: many images, turnaround batches, quick clips, and agents that call Flow often. Full measurements: [REPORT.md](REPORT.md). Wire protocol: [poc/NOTES.md](poc/NOTES.md).
- ## For AI agents
- Add the MCP server (this repo ships a `.mcp.json` for Claude Code):
- ```json
- { "mcpServers": { "flowfast": { "command": "flowfast", "args": ["mcp"] } } }
- ```
- | tool | use it for | cost |
- |---|---|---|
- | `generate_image` | text → image (1–4) | free |
- | `generate_image_from_references` | edit / restyle / combine images (absolute paths or media ids) | free |
- | `generate_views` | 3D turnaround: many assets × back/left/right/… in parallel | free |
- | `generate_video` | text → video, or image → video with `start_image`; `upscale="1080p"` also saves the 1080p version | **credits** |
- | `upscale_video` | 1080p version of a finished clip (mp4 path or workflow id) | free |
- | `list_video_models`, `get_credits`, `create_project` | catalog with prices, balance, projects | free |
- Rules of thumb: pass **absolute** paths; reuse a returned `media_id` (or the saved file, which has a `.flow.json` sidecar) instead of re-uploading; check `list_video_models` before choosing a video model; video calls block until the clip is rendered (~25–60 s).
- From a shell, `flowfast` with no arguments prints an overview, and `flowfast <command> -h` shows every option with examples. All commands print JSON.
- ---
- ## Contents
- 1. [Install](#install)
- 2. [Quick start](#quick-start)
- 3. [Commands](#commands)
- 4. [Video](#video)
- 5. [Upscale](#upscale)
- 6. [Reusing a generated image as ingredient (chaining)](#reusing-a-generated-image-as-ingredient-chaining)
- 7. [3D turnaround views](#3d-turnaround-views)
- 8. [HTTP API daemon](#http-api-daemon)
- 9. [MCP server](#mcp-server)
- 10. [Python API](#python-api)
- 11. [Models, aspects, costs](#models-aspects-costs)
- 12. [How it works](#how-it-works)
- 13. [Reliability: retries and errors](#reliability-retries-and-errors)
- 14. [When it breaks: compare with gflow-cli](#when-it-breaks-compare-with-gflow-cli)
- 15. [Troubleshooting](#troubleshooting)
- 16. [Limitations](#limitations)
- 17. [Project layout](#project-layout)
- 18. [Credits and license](#credits-and-license)
- ## Install
- Requirements: Windows or macOS, Google Chrome, and [uv](https://docs.astral.sh/uv/).
- 1. **gflow-cli, signed in once.** flowfast uses its signed-in Chrome profile:
- ```shell
- uv tool install gflow-cli
- gflow auth login
- ```
- 2. **flowfast as a command:**
- ```shell
- git clone https://github.com/JvanLeeuwen4/flowfast
- cd flowfast
- uv tool install --editable .
- flowfast --version
- ```
- `--editable` means code changes in this folder take effect without reinstalling. Afterwards `flowfast` works from any folder. Remove it with `uv tool uninstall flowfast`. If downloading a new Playwright is slow, reuse the version gflow-cli already has: `uv tool install --editable . --with playwright==1.61.0`.
- On Windows, run this in **your own terminal**, not only inside the Claude desktop app. That app runs as a Windows package and redirects its writes to `%APPDATA%` into its own package folder, so an install made from there may be invisible outside it.
- flowfast does not import gflow-cli. It only reads gflow-cli's files to find the profile:
- | setting | meaning |
- |---|---|
- | `FLOWFAST_PROFILE_DIR` | full path of a Chrome profile to use (wins over everything) |
- | `FLOWFAST_PROFILE` / `GFLOW_CLI_PROFILE` | profile name |
- | `default_profile` in gflow-cli's `config.toml` | gflow-cli's default (normally used) |
- | `GFLOW_CLI_HOME` | gflow-cli home folder, if not the default |
- gflow-cli's default home is `%LOCALAPPDATA%\ffroliva\gflow-cli` on Windows, `~/Library/Application Support/gflow-cli` on macOS and `~/.local/share/gflow-cli` on Linux.
- **gflow-cli and flowfast cannot use the profile at the same time** (Chrome locks it). Stop the daemon before running gflow-cli, and vice versa.
- ## Quick start
- **Recommended: keep the daemon running and use the CLI as usual.** The CLI detects a daemon on `127.0.0.1:8765` automatically.
- ```shell
- # terminal 1: warm daemon (closes its hidden browser after 10 min idle, restarts on demand)
- flowfast serve
- # terminal 2
- flowfast t2i "a pastel toy lighthouse, 3D render, plain white background" --name lighthouse
- flowfast i2i "same object seen from directly behind" --ref out/lighthouse.jpg --name lighthouse_back
- flowfast video "slow 360 degree turntable rotation, camera static" --start out/lighthouse.jpg --upscale 1080p
- ```
- Without a daemon (or with `--local`), each command starts and stops its own hidden browser: ~11–12 s per image. In testing, the first token of a fresh browser was sometimes flagged by Flow (see [reliability](#reliability-retries-and-errors)). The warm daemon never was.
- Output lands in `./out` (change with `--out`). Next to every file, flowfast writes a `<name>.flow.json` sidecar (see [chaining](#reusing-a-generated-image-as-ingredient-chaining)).
- ## Commands
- | command | does | cost | speed |
- |---|---|---|---|
- | `flowfast t2i` | text → image, 1–4 per call | free | ~7 s warm |
- | `flowfast i2i` | image(s) + text → image (edit, restyle, combine) | free | ~7–20 s |
- | `flowfast views` | 3D turnaround: N assets × back/left/right/… in parallel | free | 8 × 3 in ~2.5 min |
- | `flowfast video` | text → video, or image → video with `--start` | **credits** (4–12) | ~25–60 s |
- | `flowfast upscale` | 1080p version of a finished clip | free | ~40 s |
- | `flowfast models` | Flow's live video model list with credit prices | free | |
- | `flowfast fetch` | re-download an existing video by workflow id | free | |
- | `flowfast credits` | credit balance | free | |
- | `flowfast serve` | warm daemon on `127.0.0.1:8765`; the CLI uses it automatically | | |
- | `flowfast mcp` | MCP server (stdio) for Claude Code and other agents | | |
- | `flowfast status` | state of the running daemon | | |
- ```
- flowfast t2i "prompt" [-n 1-4] [--name stem] [--model nano2-lite] [--aspect 1:1]
- flowfast i2i "prompt" --ref <path|media_id> [--ref ...] [--name stem] [--model nano2]
- flowfast views <path|media_id> ... [--views back,left,right] [--template "...{view}..."]
- flowfast video "prompt" [--start <path|media_id>] [--model veo-lite] [--duration N] [--aspect 16:9] [--upscale 1080p]
- flowfast upscale <clip.mp4|workflow_id> [--scale 1080p] [--name stem]
- flowfast models [--all] [--json]
- flowfast fetch <workflow_id> [--out DIR] [--name stem]
- flowfast credits | status
- flowfast serve [--port 8765] [--idle 600] [--out DIR] [--no-prewarm]
- flowfast mcp
- ```
- Shared options for `t2i` / `i2i` / `views` / `video`:
- | option | default | meaning |
- |---|---|---|
- | `--model` | `nano2-lite` (t2i), `nano2` (i2i, views), `veo-lite` (video) | see [models](#models-aspects-costs) |
- | `--aspect` | `1:1` (images), `16:9` (video) | images: `1:1 16:9 9:16 4:3 3:4`; video: `16:9 9:16` |
- | `--project` | one session project | generate in an existing Flow project |
- | `--out` | `out` | output folder |
- | `--name` | media id | output file stem (t2i, i2i, video) |
- | `--parallel` | `8` | max generations in flight (in-process runs) |
- | `--daemon URL` | auto: `http://127.0.0.1:8765` when it answers | send the job to a running `serve` |
- | `--local` | off | run in-process (own cold browser) even when a daemon is up |
- All commands print JSON: the project id, the reference media ids used, the `media_id` and local `path` of each result, and per-step `timings` (`ready`, `upload`, `mint`, `generate`/`submit`+`render`, `download`, `total`, and `retries` when one happened).
- `python -m flowfast ...` still works too, for a machine where flowfast is not installed as a command.
- ## Video
- ```shell
- flowfast video "a red paper boat drifting on a calm pond" --model omni-360p --duration 4 # 4 credits
- flowfast video "slow 360 degree turntable rotation of the building, camera static, plain background" \
- --start assets/bakery.jpg # 10 credits
- flowfast models # live list of every video model with its price
- ```
- **Video costs credits; images do not.** Prices on a tier-1 account (from Flow's own catalog via `flowfast models`):
- | `--model` | Flow key (t2v / i2v) | length | resolution | credits |
- |---|---|---|---|---|
- | `veo-lite` (default) | `veo_3_1_t2v_lite` / `veo_3_1_i2v_lite` | 8 s | 1280×720 | 10 |
- | `omni-360p` | `macaron_cookie_t2v_<N>s_360p` / `..._i2v_<N>s_360p` | 3–10 s | 640×360 | 1 per second (4 s = 4) |
- | `omni` (Omni 1.2 Flash) | `macaron_cookie_t2v_<N>s` / `..._i2v_<N>s` | 3–10 s | 720p | 3 per second (4 s = 12) |
- | any raw key | e.g. `veo_3_1_t2v_fast` | per key | | see `flowfast models` |
- `--duration` picks the length (omni: 3–10; veo-lite only 8 s on tier 1). On tier 1 the 4 s/6 s Veo Lite keys and the "Lower Priority" (free) keys are not offered. Flow then refuses the submit, and no credits are spent.
- What happens on a call:
- 1. With `--start`: the image is uploaded (or reused via media id / sidecar, as with i2i). It is cropped centrally to the video aspect, exactly as the web composer does.
- 2. Submit: `YhhmEf` (t2v) or `eb1hJf` (i2v), with a `VIDEO_GENERATION` token. Returns at once.
- 3. Poll `jwpduf` every 5 s (the same poll the web app runs) until the status is *done*.
- 4. `as29s` returns a signed `flow-content.google/video/...` URL. flowfast downloads the original mp4 and checks the byte size against what Flow reported.
- 5. `<name>.mp4` plus `<name>.flow.json` (media id, workflow id, model key, prompt, start frame).
- 6. With `--upscale 1080p`: the [upscale](#upscale) runs right after, giving `<name>_1080p.mp4` as well.
- **A submit is never sent twice unless Flow explicitly refused it** (`UNUSUAL_ACTIVITY`), so one call cannot bill twice. If a download fails after rendering, the clip is not lost: `flowfast fetch <workflow_id>` downloads it again for free (the workflow id is in the JSON output and the error message).
- Measured: i2v Veo Lite from a 1024² concept image: upload 48.7 s (cold), submit 4.5 s, **render 33.8 s**, download 1.8 s. t2v Omni 360p 4 s: submit 4.6 s, **render 22.8 s**. Both 16:9 outputs verified (1280×720, 640×360). Rendering happens at Google; the CLI only polls.
- **Not implemented:** start + end frame (`nprQif`), ingredients/r2v (`MZZa6b`) and extend. The keys exist in the catalog, but their request shapes have not been captured yet.
- ## Upscale
- ```shell
- flowfast upscale out/boat.mp4 # -> out/boat_1080p.mp4 (+ sidecar), free
- flowfast upscale <workflow-id> # any finished clip in your account
- flowfast video "..." --upscale 1080p # generate and upscale in one go
- ```
- This is Flow's own **Download → 1080p** from the web viewer, sent as one RPC (`p0UkFb` with the upsampler key `veo_3_1_upsampler_1080p`). Flow renders the upscaled clip as a new record `<workflow>_upsampled`; flowfast polls it, downloads the mp4 and checks that it really is 1080p (the mp4's track header, not the file name).
- | | |
- |---|---|
- | cost | **0 credits** (1080p is free on every tier) |
- | time | ~40 s (mint 4 s, submit 4 s, render ~27 s, download < 1 s) |
- | input | a flowfast mp4 (its sidecar has the ids) or a workflow id; also 360p Omni clips |
- | output | 1920×1080 (16:9) |
- | `--scale 4k` | `veo_3_1_upsampler_4k`: tier 3 only (50 credits); Flow refuses it on lower tiers, and nothing is billed |
- gflow-cli upscales the same way by opening the clip in the web editor, clicking the menu item and catching the blob. flowfast sends the RPC behind that click directly, so no page is opened.
- ## Reusing a generated image as ingredient (chaining)
- An image Flow generated already exists in Flow under its `media_id`. Pass it as reference and **no upload happens at all**. That works:
- * in the same project and in a **different** project;
- * for t2i results, i2i results and uploads alike, any number of levels deep;
- * as the `--start` frame of a video.
- Three ways to refer to an earlier result, fastest first:
- | how | example | upload |
- |---|---|---|
- | media id from the JSON output | `--ref <media-id>` | none |
- | **the local file flowfast saved** (it has a `.flow.json` sidecar) | `--ref out/base.jpg` | none (sidecar lookup) |
- | any other local file | `--ref concept.png` | once per session, then cached |
- Measured on the same i2i request (nano2-lite, warm):
- | reference | upload | total |
- |---|---|---|
- | media id | 0 s | 9.5 s |
- | local file with sidecar | 0.008 s | 6.9 s |
- | same file without sidecar | **8.2 s** | **17.5 s** |
- **The sidecar** `<stem>.flow.json` holds `media_id`, `project_id`, `workflow_id`, the `sha256` of the downloaded bytes, model, seed, size, prompt and the refs used. It holds no URLs or tokens. flowfast only reuses the `media_id` when the file's current hash matches. If you edit the file (e.g. remove the background, or retouch it), the edited file is a new image and gets uploaded normally.
- ```shell
- flowfast t2i "a pastel toy windmill, plain white background" --out out/wm --name base
- flowfast i2i "same object seen from directly behind" --ref out/wm/base.jpg --name back --out out/wm
- flowfast views out/wm/base.jpg --views back,left,right --out out/wm
- flowfast video "slow turntable rotation, camera static" --start out/wm/base.jpg --out out/wm --upscale 1080p
- ```
- ## 3D turnaround views
- `views` takes N front/concept images and produces M views of each. Every (asset, view) pair is one generation, all in flight at once (bounded by `--parallel`). Each asset is uploaded once, or not at all if it is a media id or a flowfast-generated file.
- ```shell
- flowfast views assets/windmill.jpg assets/bakery.jpg --views back,left,right --model nano2 --out views
- # -> views/windmill_back.jpg, views/windmill_left.jpg, ..., each with a .flow.json
- ```
- Known views: `back`, `left`, `right`, `front`, `front_left`, `front_right`, `back_left`, `back_right`, `top`. The default prompt template:
- > The exact same object as in the reference image, seen **{view}**, same camera height and 3/4 elevation, same scale, same style, colours and materials, centred on a plain white background. Show only what is visible from this side; do not copy details that only exist on other sides.
- Override it with `--template "... {view} ..."`. With a custom template you may also pass free-text view names.
- **Measured:** 8 game-asset concepts × back/left/right = 24 images in **2 min 38 s**, 24/24 OK, 0 credits.
- **Quality note:** *back* and *right* came out as real side views on the windmill test asset. *left* came out as a 3/4 front view. For assets where it matters, tune the view phrasing (e.g. "pure side profile, sails seen edge-on"). An image-to-video turntable (`flowfast video --start`) is an alternative: one clip shows every side, and frames can be taken from it.
- ## HTTP API daemon
- ```shell
- flowfast serve --port 8765 --idle 600 --out /path/to/out
- ```
- The daemon binds to `127.0.0.1` only. On start it pre-warms (browser + session project + armed page, ~9 s) unless `--no-prewarm` is passed.
- | method | path | body | returns |
- |---|---|---|---|
- | POST | `/t2i` | `{"prompt", "model"?, "aspect"?, "count"?, "project"?, "out_name"?, "out_dir"?}` | generate result |
- | POST | `/i2i` | `{"prompt", "refs": [path or media_id, ...], ...same...}` | generate result |
- | POST | `/views` | `{"assets": [...], "views"?, "template"?, "model"?, "aspect"?, "out_dir"?}` | `{wall_s, ok, failed, images_per_min, results[]}` |
- | POST | `/video` | `{"prompt", "start"?, "model"?, "duration"?, "aspect"?, "upscale"?, "out_name"?, "out_dir"?}` | video result (waits for the render) |
- | POST | `/upscale` | `{"source": path or workflow_id, "scale"?, "aspect"?, "out_name"?, "out_dir"?}` | upscaled video |
- | POST | `/fetch` | `{"workflow_id", "out_dir"?, "out_name"?}` | re-downloaded video |
- | GET | `/models` | – | live video catalog |
- | GET | `/credits` | – | `{"credits": 100}` |
- | POST | `/projects` | `{"title"}` | `{"project_id"}` |
- | GET | `/status` | – | browser state, launches, mints, uploads, refs by media id / sidecar / cache, retries |
- Paths are paths **on the daemon's machine**; the CLI makes them absolute for you. Errors: `400` for bad input, `502` with `{"error", "status"}` when Flow rejects a call.
- ## MCP server
- A stdio MCP server over the same engine; the browser stays warm for the whole session. Config and tool list: see [For AI agents](#for-ai-agents). Argument details:
- | tool | arguments |
- |---|---|
- | `generate_image` | `prompt, model, aspect, count, project_id` |
- | `generate_image_from_references` | `prompt, references[], model, aspect, count, project_id, output_name` |
- | `generate_views` | `assets[], views[], model, aspect, output_dir, template` |
- | `generate_video` | `prompt, start_image, model, duration, aspect, project_id, output_name, upscale` |
- | `upscale_video` | `source, scale, aspect, output_dir, output_name` |
- | `list_video_models`, `get_credits` | – |
- | `create_project` | `title` |
- ## Python API
- ```python
- import asyncio
- from pathlib import Path
- from flowfast import Engine
- async def main():
- eng = Engine(out_dir=Path("out"), max_parallel=8, idle_shutdown_s=0)
- try:
- base = await eng.t2i("a pastel toy windmill, plain white background", model="nano2", out_name="windmill")
- mid = base["images"][0]["media_id"]
- await eng.i2i("same object seen from directly behind", [mid], model="nano2", out_name="windmill_back")
- await eng.views([mid], views=["left", "right"], model="nano2")
- await eng.video("slow turntable rotation, camera static", start=mid, out_name="windmill_spin",
- upscale="1080p")
- print(await eng.credits(), eng.status())
- finally:
- await eng.aclose()
- asyncio.run(main())
- ```
- | method | does |
- |---|---|
- | `t2i(prompt, *, model, aspect, count, project, out_dir, out_name, download)` | text-to-image |
- | `i2i(prompt, refs, *, ...)` | image-to-image; `refs` = paths and/or media ids |
- | `views(assets, *, views, template, model, aspect, out_dir, project)` | N assets × M views, parallel |
- | `video(prompt, *, start, model, duration, aspect, project, out_dir, out_name, upscale, timeout_s)` | t2v / i2v, waits for the render |
- | `upscale(source, *, scale, aspect, out_dir, out_name)` | 1080p version of a clip (mp4 path or workflow id) |
- | `fetch_video(workflow_id, *, out_dir, out_name)`, `models()` | re-download a clip; live catalog |
- | `upload(path_or_media_id, *, project)` | → `(media_id, filename)`; cached, sidecar-aware |
- | `credits()`, `create_project(title)`, `status()`, `aclose()` | |
- Lower level: `flowfast.wire.FlowWire` (raw RPCs) and `flowfast.minter.Minter` (token page).
- ## Models, aspects, costs
- Images:
- | alias | Flow wire name | t2i time | i2i time | credits (tier 1) |
- |---|---|---|---|---|
- | `nano2-lite` | `HARBOR_SEAL` | ~7 s | ~7–9 s | 0 |
- | `nano2` (Nano Banana 2.1) | `BELUGA` | ~17 s | 20–70 s | 0 |
- | `nano-pro` (Nano Banana Pro) | `GEM_PIX_2` | ~18 s | – | 0 |
- * gflow-cli's older names `NARWHAL` (nano2) and `IMAGEN_3_5` (Imagen 4) are rejected on flow.google.com with rpc code 5, so Imagen 4 is unavailable.
- * Image sizes: `1:1` 1024×1024 · `16:9` 1376×768 · `9:16` 768×1376 · `4:3` 1200×896 · `3:4` 896×1200.
- Video: see [Video](#video), and `flowfast models` for the full live list (219 keys at the time of writing, with which tier may use each and its price). Credit costs were measured by reading the balance (`nzlxg`) before and after each call. Upscale: see [Upscale](#upscale).
- ## How it works
- ```
- caller (CLI / HTTP / MCP / Python)
- │
- ▼
- Engine ────────── httpx ─────────► flow.google.com/_/AiSandboxAngularFrontend/data/batchexecute
- │ jHPbke create project nzlxg credits
- │ maseQ upload image HTrJv video model catalog
- │ ogiZ0b generate image(s) YhhmEf submit t2v
- │ eb1hJf submit i2v jwpduf video status poll
- │ p0UkFb upscale video as29s media record (signed URL)
- │ flow-content.google signed image / video download
- │
- └─► Minter: ONE headless Chrome page (gflow-cli's profile)
- - loads one Flow project page once (that page carries recaptcha/enterprise.js)
- - per request: grecaptcha.enterprise.execute(siteKey, {action}) ~0.14 s
- - hands its live cookies to httpx
- ```
- * **Everything except the token goes over HTTP.** There are no clicks or DOM selectors, so Flow UI changes do not break it (wire-format changes still can, see [When it breaks](#when-it-breaks-compare-with-gflow-cli)).
- * **Tokens are single-use with a ~2 min lifetime.** flowfast mints one right before each call: `UPLOAD_IMAGE`, `IMAGE_GENERATION` or `VIDEO_GENERATION`.
- * **One armed page serves every project**, so the browser never navigates again after start-up.
- * **Uploads are cached** (by content hash + project), and parallel callers share one upload.
- * Generations run **concurrently** (default 8 in flight). Token minting is serialized, but takes only ~0.14 s.
- * The browser starts lazily on the first call. In the daemon it closes after `--idle` seconds without work and relaunches automatically.
- ## Reliability: retries and errors
- * **Images and uploads** are attempted up to 3 times, each with a freshly minted token. `PUBLIC_ERROR_UNUSUAL_ACTIVITY` (rpc code 7, Flow's reCAPTCHA/abuse signal) gets a 2 s and then a 5 s pause before the re-mint. Other wire errors retry after 0.2 s.
- * **Video submits and upscales** retry only on `UNUSUAL_ACTIVITY` (a refused submit is not billed). Any other failure is raised at once, so no clip is billed twice.
- * `UNUSUAL_ACTIVITY` showed up on reused/expired tokens and **on fresh browsers**: 3 of ~20 cold processes were flagged, once even after all 3 attempts. **No warm call** (~65) was. The real fix is one warm daemon instead of launching browsers in a loop.
- * A stale page token (`at`, HTTP 400/401) is refreshed once automatically.
- * The token page waits until `grecaptcha.enterprise` has fully loaded before the first mint.
- * In `views`, one failing (asset, view) is reported in `results` and does not stop the batch.
- ## When it breaks: compare with gflow-cli
- flowfast speaks Flow's **private, undocumented** web protocol, copied from what the flow.google.com app sends. Google can change it at any deploy. Typical symptoms:
- * an RPC returns an error code (`[3]` invalid argument, `[5]` not found) for a call that used to work;
- * a parse error, `no generation record`, or an empty result;
- * the token page cannot find the reCAPTCHA site key;
- * a model name is rejected, or a download returns HTML instead of an image or mp4.
- **First, look at what the original gflow-cli changed.** gflow-cli drives the real web UI and is actively maintained against these changes. Its code and changelog document every protocol detail flowfast relies on:
- 1. **Check whether gflow-cli itself still works** for the same thing: `gflow-cli image t2i ...` / `gflow-cli video t2v ...`. Stop the flowfast daemon first (profile lock).
- * gflow-cli works but flowfast does not → the wire format changed. Go on with step 2.
- * Both fail → it is the account or session (`gflow auth login`), or a Flow outage.
- 2. **Read gflow-cli's changes:** `gflow update`, then the [CHANGELOG](https://github.com/ffroliva/gflow-cli/blob/main/CHANGELOG.md) and recent commits. Look for "migrated host", rpc ids, model keys and reCAPTCHA. The installed source is the `gflow_cli` package in gflow-cli's tool environment (`uv tool dir` shows where). Files to diff:
- | flowfast part | where gflow-cli keeps it |
- |---|---|
- | rpc ids, record shape, status codes (`wire.py`) | `api/transports/batchexecute.py`, constants at the top of `api/transports/migrated_composer.py` (`SUBMIT_RPCS`, `STATUS_RPCS`, `UPLOAD_RPC`, `CREDITS_RPC`, `CREATE_PROJECT_RPC`) |
- | image model names (`MODELS`) | `data/models.py`, `api/transports/migrated_composer.py` |
- | video model keys, durations | `api/transports/migrated_composer.py` (`VIDEO_MODEL_MENU_LABELS`, key comments), `flowfast models` (live) |
- | video upscale (`upscale_video`) | `api/transports/migrated_video_upscale.py` (it clicks the menu; the RPCs it watches are `p0UkFb` and `jwpduf`) |
- | profile location, Chrome channel (`engine._gflow_profile`) | `paths.py`, `profile_store.py`, `browser_manager.channel_for_profile` |
- | video download URL | `api/transports/migrated_recover.py` |
- 3. **Capture what the web app sends now.** gflow-cli can record a HAR of a real run:
- ```shell
- GFLOW_CLI_HAR_PATH="$PWD/poc/har/new.har" gflow-cli video t2v "test" --json
- ```
- (PowerShell: `$env:GFLOW_CLI_HAR_PATH = "$PWD\poc\har\new.har"` first.) Then compare the `f.req` body of the relevant rpc with the payload `flowfast/wire.py` builds. The extraction script is in [poc/NOTES.md](poc/NOTES.md). Images and upscales are free to capture; a video capture costs one clip. **HAR files hold your session cookies: never commit or share them** (`*.har` is git-ignored).
- 4. **Fix `flowfast/wire.py`** (payload shapes, rpc ids, model names) and record the new shape in `poc/NOTES.md`.
- Note that gflow-cli sometimes lags too. At one point its video download failed (`signed media URL returned HTTP 302`) while flowfast's download worked, because flowfast asks `as29s` for the direct `flow-content.google/video/...` link. So treat gflow-cli as a reference, not an oracle.
- ## Troubleshooting
- | symptom | cause / fix |
- |---|---|
- | `SignedOut: app shell carries no 'at' token` | The profile session expired. Run `gflow auth login`. |
- | gflow-cli says *Profile locked* | A flowfast daemon / MCP server / CLI run holds the profile. Stop it. |
- | `no gflow-cli profile to use` | No profile found. Run `gflow auth login`, or set `FLOWFAST_PROFILE_DIR`. |
- | `... [5]` on generate | Unknown model name or media id (NOT_FOUND). |
- | `... [3]` on a video submit | That model key is not allowed on your tier, or the request shape changed. Check `flowfast models`; see [When it breaks](#when-it-breaks-compare-with-gflow-cli). |
- | `UNUSUAL_ACTIVITY` after 3 attempts | Usually a cold browser: start `flowfast serve` and let the CLI use it. On a warm daemon, pause a few minutes and lower `--parallel`. |
- | `reCAPTCHA not ready after 20s` | The project page did not load (network or sign-in). Retry; check `gflow auth status`. |
- | video download failed | The clip still exists: `flowfast fetch <workflow_id>` (free). |
- | upscale: `got (1280, 720), not 1080p` | Flow returned the original instead of the upscale. Re-run; it is free. |
- | HTTP 429 / 503 | Throttled. Lower `--parallel` and wait. |
- ## Limitations
- * Video: start+end frame, ingredients (r2v) and extend are not implemented. Image upscale (2K/4K) is not implemented either; gflow-cli has it (`gflow image upscale`).
- * 9:16 video and 9:16 upscale use the catalog's aspect enum, but have not been verified with a render.
- * Parallelism above 8 has not been tested.
- * The wire format is reverse-engineered from build `boq_labs-ai-sandbox-frontend_20261111.08` and can break on any Flow deploy.
- * Reference images are uploaded unscaled.
- * Long-running behaviour (cookie rotation over hours or days) is not measured. The engine re-reads cookies every 5 minutes.
- * It uses private, undocumented Google endpoints with your own account, and is subject to Flow's terms.
- ## Project layout
- ```
- flowfast/
- wire.py Flow batchexecute RPCs over httpx (no browser): images, video, upscale, catalog, downloads
- minter.py the one headless page: reCAPTCHA tokens + live cookies
- engine.py orchestration: lazy start, session project, upload cache, sidecars, retries, views, video
- api.py FastAPI daemon (flowfast serve)
- mcp_server.py MCP stdio server (flowfast mcp)
- __main__.py CLI (flowfast)
- pyproject.toml package + `flowfast` command (uv tool install --editable .)
- bench/
- run_tests.py image test & benchmark harness (T1-T19); raw output -> bench/out/ (not committed)
- video_test.py live video test (t2v + i2v + upscale); costs ~14 credits
- poc/
- NOTES.md captured wire map (rpc ids, payload shapes, reCAPTCHA actions)
- video_models.txt Flow's video catalog as captured
- REPORT.md test report with all measurements
- .mcp.json MCP config for Claude Code
- LICENSE MIT
- ```
- ## Credits and license
- * **[gflow-cli](https://github.com/ffroliva/gflow-cli)** by [@ffroliva](https://github.com/ffroliva) does the hard part: the Flow login, the browser profile, and a maintained map of Flow's web protocol that flowfast follows. If flowfast is useful to you, star gflow-cli too.
- * flowfast is released under the [MIT License](LICENSE). It is an independent project, not affiliated with or endorsed by Google or the gflow-cli authors.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.