Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jvanleeuwen4--flowfast/badge.svg)](/listings/jvanleeuwen4--flowfast)

HTML

<a href="/listings/jvanleeuwen4--flowfast"><img src="/api/listings/jvanleeuwen4--flowfast/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
  1. # flowfast
  2. **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.
  3. 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.
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
  6. ![Windows | macOS](https://img.shields.io/badge/tested-Windows%20%7C%20macOS-lightgrey)
  7. ![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2)
  8. | one image (nano2-lite, warm) | 24 turnaround views (8 assets × 3) | one video (Veo 3.1 Lite, i2v) | 1080p upscale of a clip |
  9. |---|---|---|---|
  10. | 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** |
  11. > **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.
  12. ---
  13. ## At a glance (for people and agents)
  14. * **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).
  15. * **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).
  16. * **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.
  17. * **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).
  18. * **Interfaces:** `flowfast` CLI · `flowfast serve` (HTTP on `127.0.0.1:8765`) · `flowfast mcp` (stdio MCP server) · `from flowfast import Engine`.
  19. * **Cost:** images and the 1080p upscale are free on Flow. **Video generation costs Flow credits** (4–12 per clip on the cheap models).
  20. * **Tested on** Windows 11 and macOS, with a tier-1 account.
  21. ## How it differs from gflow-cli
  22. ```mermaid
  23. flowchart LR
  24. subgraph G["gflow-cli: UI automation"]
  25. direction TB
  26. g1["your command"] --> g2["Playwright opens Chrome<br/>and loads the full Flow app"]
  27. g2 --> g3["types the prompt, clicks<br/>Generate, watches the page"]
  28. g3 --> g4["Flow backend"]
  29. end
  30. subgraph F["flowfast: direct RPCs"]
  31. direction TB
  32. f1["your command"] --> f2["httpx sends Flow's own<br/>batchexecute RPCs"]
  33. f1 -.->|"one token per request, ~0.14 s"| f3["one hidden Chrome page<br/>grecaptcha.enterprise.execute()"]
  34. f3 -.-> f2
  35. f2 --> f4["Flow backend"]
  36. end
  37. P[("gflow-cli's signed-in<br/>Chrome profile")] --> g2
  38. P --> f3
  39. ```
  40. | | gflow-cli | flowfast |
  41. |---|---|---|
  42. | Talks to Flow via | the web UI (Playwright: load, type, click) | Flow's backend RPCs over HTTP |
  43. | Browser work per image | 3 full app loads, typing, clicking | 1 `evaluate` call (**0.14 s**) on an already open page |
  44. | One image, wall time | 19.8 s | **7.8 s** warm (≈ Google's own ~6.9 s render) |
  45. | Throughput | ~3 images/min | **44.5 images/min** (8 in parallel) |
  46. | Breaks when | Flow's UI or protocol changes | Flow's protocol changes (UI changes don't matter) |
  47. | Feature coverage | broad: images, video, extend, scenes, characters, upscale, … | focused: t2i, i2i, views, t2v, i2v, 1080p video upscale |
  48. | Login | `gflow auth login` | reuses gflow-cli's profile |
  49. **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).
  50. ## For AI agents
  51. Add the MCP server (this repo ships a `.mcp.json` for Claude Code):
  52. ```json
  53. { "mcpServers": { "flowfast": { "command": "flowfast", "args": ["mcp"] } } }
  54. ```
  55. | tool | use it for | cost |
  56. |---|---|---|
  57. | `generate_image` | text → image (1–4) | free |
  58. | `generate_image_from_references` | edit / restyle / combine images (absolute paths or media ids) | free |
  59. | `generate_views` | 3D turnaround: many assets × back/left/right/… in parallel | free |
  60. | `generate_video` | text → video, or image → video with `start_image`; `upscale="1080p"` also saves the 1080p version | **credits** |
  61. | `upscale_video` | 1080p version of a finished clip (mp4 path or workflow id) | free |
  62. | `list_video_models`, `get_credits`, `create_project` | catalog with prices, balance, projects | free |
  63. 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).
  64. From a shell, `flowfast` with no arguments prints an overview, and `flowfast <command> -h` shows every option with examples. All commands print JSON.
  65. ---
  66. ## Contents
  67. 1. [Install](#install)
  68. 2. [Quick start](#quick-start)
  69. 3. [Commands](#commands)
  70. 4. [Video](#video)
  71. 5. [Upscale](#upscale)
  72. 6. [Reusing a generated image as ingredient (chaining)](#reusing-a-generated-image-as-ingredient-chaining)
  73. 7. [3D turnaround views](#3d-turnaround-views)
  74. 8. [HTTP API daemon](#http-api-daemon)
  75. 9. [MCP server](#mcp-server)
  76. 10. [Python API](#python-api)
  77. 11. [Models, aspects, costs](#models-aspects-costs)
  78. 12. [How it works](#how-it-works)
  79. 13. [Reliability: retries and errors](#reliability-retries-and-errors)
  80. 14. [When it breaks: compare with gflow-cli](#when-it-breaks-compare-with-gflow-cli)
  81. 15. [Troubleshooting](#troubleshooting)
  82. 16. [Limitations](#limitations)
  83. 17. [Project layout](#project-layout)
  84. 18. [Credits and license](#credits-and-license)
  85. ## Install
  86. Requirements: Windows or macOS, Google Chrome, and [uv](https://docs.astral.sh/uv/).
  87. 1. **gflow-cli, signed in once.** flowfast uses its signed-in Chrome profile:
  88. ```shell
  89. uv tool install gflow-cli
  90. gflow auth login
  91. ```
  92. 2. **flowfast as a command:**
  93. ```shell
  94. git clone https://github.com/JvanLeeuwen4/flowfast
  95. cd flowfast
  96. uv tool install --editable .
  97. flowfast --version
  98. ```
  99. `--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`.
  100. 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.
  101. flowfast does not import gflow-cli. It only reads gflow-cli's files to find the profile:
  102. | setting | meaning |
  103. |---|---|
  104. | `FLOWFAST_PROFILE_DIR` | full path of a Chrome profile to use (wins over everything) |
  105. | `FLOWFAST_PROFILE` / `GFLOW_CLI_PROFILE` | profile name |
  106. | `default_profile` in gflow-cli's `config.toml` | gflow-cli's default (normally used) |
  107. | `GFLOW_CLI_HOME` | gflow-cli home folder, if not the default |
  108. 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.
  109. **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.
  110. ## Quick start
  111. **Recommended: keep the daemon running and use the CLI as usual.** The CLI detects a daemon on `127.0.0.1:8765` automatically.
  112. ```shell
  113. # terminal 1: warm daemon (closes its hidden browser after 10 min idle, restarts on demand)
  114. flowfast serve
  115. # terminal 2
  116. flowfast t2i "a pastel toy lighthouse, 3D render, plain white background" --name lighthouse
  117. flowfast i2i "same object seen from directly behind" --ref out/lighthouse.jpg --name lighthouse_back
  118. flowfast video "slow 360 degree turntable rotation, camera static" --start out/lighthouse.jpg --upscale 1080p
  119. ```
  120. 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.
  121. 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)).
  122. ## Commands
  123. | command | does | cost | speed |
  124. |---|---|---|---|
  125. | `flowfast t2i` | text → image, 1–4 per call | free | ~7 s warm |
  126. | `flowfast i2i` | image(s) + text → image (edit, restyle, combine) | free | ~7–20 s |
  127. | `flowfast views` | 3D turnaround: N assets × back/left/right/… in parallel | free | 8 × 3 in ~2.5 min |
  128. | `flowfast video` | text → video, or image → video with `--start` | **credits** (4–12) | ~25–60 s |
  129. | `flowfast upscale` | 1080p version of a finished clip | free | ~40 s |
  130. | `flowfast models` | Flow's live video model list with credit prices | free | |
  131. | `flowfast fetch` | re-download an existing video by workflow id | free | |
  132. | `flowfast credits` | credit balance | free | |
  133. | `flowfast serve` | warm daemon on `127.0.0.1:8765`; the CLI uses it automatically | | |
  134. | `flowfast mcp` | MCP server (stdio) for Claude Code and other agents | | |
  135. | `flowfast status` | state of the running daemon | | |
  136. ```
  137. flowfast t2i "prompt" [-n 1-4] [--name stem] [--model nano2-lite] [--aspect 1:1]
  138. flowfast i2i "prompt" --ref <path|media_id> [--ref ...] [--name stem] [--model nano2]
  139. flowfast views <path|media_id> ... [--views back,left,right] [--template "...{view}..."]
  140. flowfast video "prompt" [--start <path|media_id>] [--model veo-lite] [--duration N] [--aspect 16:9] [--upscale 1080p]
  141. flowfast upscale <clip.mp4|workflow_id> [--scale 1080p] [--name stem]
  142. flowfast models [--all] [--json]
  143. flowfast fetch <workflow_id> [--out DIR] [--name stem]
  144. flowfast credits | status
  145. flowfast serve [--port 8765] [--idle 600] [--out DIR] [--no-prewarm]
  146. flowfast mcp
  147. ```
  148. Shared options for `t2i` / `i2i` / `views` / `video`:
  149. | option | default | meaning |
  150. |---|---|---|
  151. | `--model` | `nano2-lite` (t2i), `nano2` (i2i, views), `veo-lite` (video) | see [models](#models-aspects-costs) |
  152. | `--aspect` | `1:1` (images), `16:9` (video) | images: `1:1 16:9 9:16 4:3 3:4`; video: `16:9 9:16` |
  153. | `--project` | one session project | generate in an existing Flow project |
  154. | `--out` | `out` | output folder |
  155. | `--name` | media id | output file stem (t2i, i2i, video) |
  156. | `--parallel` | `8` | max generations in flight (in-process runs) |
  157. | `--daemon URL` | auto: `http://127.0.0.1:8765` when it answers | send the job to a running `serve` |
  158. | `--local` | off | run in-process (own cold browser) even when a daemon is up |
  159. 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).
  160. `python -m flowfast ...` still works too, for a machine where flowfast is not installed as a command.
  161. ## Video
  162. ```shell
  163. flowfast video "a red paper boat drifting on a calm pond" --model omni-360p --duration 4 # 4 credits
  164. flowfast video "slow 360 degree turntable rotation of the building, camera static, plain background" \
  165. --start assets/bakery.jpg # 10 credits
  166. flowfast models # live list of every video model with its price
  167. ```
  168. **Video costs credits; images do not.** Prices on a tier-1 account (from Flow's own catalog via `flowfast models`):
  169. | `--model` | Flow key (t2v / i2v) | length | resolution | credits |
  170. |---|---|---|---|---|
  171. | `veo-lite` (default) | `veo_3_1_t2v_lite` / `veo_3_1_i2v_lite` | 8 s | 1280×720 | 10 |
  172. | `omni-360p` | `macaron_cookie_t2v_<N>s_360p` / `..._i2v_<N>s_360p` | 3–10 s | 640×360 | 1 per second (4 s = 4) |
  173. | `omni` (Omni 1.2 Flash) | `macaron_cookie_t2v_<N>s` / `..._i2v_<N>s` | 3–10 s | 720p | 3 per second (4 s = 12) |
  174. | any raw key | e.g. `veo_3_1_t2v_fast` | per key | | see `flowfast models` |
  175. `--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.
  176. What happens on a call:
  177. 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.
  178. 2. Submit: `YhhmEf` (t2v) or `eb1hJf` (i2v), with a `VIDEO_GENERATION` token. Returns at once.
  179. 3. Poll `jwpduf` every 5 s (the same poll the web app runs) until the status is *done*.
  180. 4. `as29s` returns a signed `flow-content.google/video/...` URL. flowfast downloads the original mp4 and checks the byte size against what Flow reported.
  181. 5. `<name>.mp4` plus `<name>.flow.json` (media id, workflow id, model key, prompt, start frame).
  182. 6. With `--upscale 1080p`: the [upscale](#upscale) runs right after, giving `<name>_1080p.mp4` as well.
  183. **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).
  184. 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.
  185. **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.
  186. ## Upscale
  187. ```shell
  188. flowfast upscale out/boat.mp4 # -> out/boat_1080p.mp4 (+ sidecar), free
  189. flowfast upscale <workflow-id> # any finished clip in your account
  190. flowfast video "..." --upscale 1080p # generate and upscale in one go
  191. ```
  192. 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).
  193. | | |
  194. |---|---|
  195. | cost | **0 credits** (1080p is free on every tier) |
  196. | time | ~40 s (mint 4 s, submit 4 s, render ~27 s, download < 1 s) |
  197. | input | a flowfast mp4 (its sidecar has the ids) or a workflow id; also 360p Omni clips |
  198. | output | 1920×1080 (16:9) |
  199. | `--scale 4k` | `veo_3_1_upsampler_4k`: tier 3 only (50 credits); Flow refuses it on lower tiers, and nothing is billed |
  200. 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.
  201. ## Reusing a generated image as ingredient (chaining)
  202. An image Flow generated already exists in Flow under its `media_id`. Pass it as reference and **no upload happens at all**. That works:
  203. * in the same project and in a **different** project;
  204. * for t2i results, i2i results and uploads alike, any number of levels deep;
  205. * as the `--start` frame of a video.
  206. Three ways to refer to an earlier result, fastest first:
  207. | how | example | upload |
  208. |---|---|---|
  209. | media id from the JSON output | `--ref <media-id>` | none |
  210. | **the local file flowfast saved** (it has a `.flow.json` sidecar) | `--ref out/base.jpg` | none (sidecar lookup) |
  211. | any other local file | `--ref concept.png` | once per session, then cached |
  212. Measured on the same i2i request (nano2-lite, warm):
  213. | reference | upload | total |
  214. |---|---|---|
  215. | media id | 0 s | 9.5 s |
  216. | local file with sidecar | 0.008 s | 6.9 s |
  217. | same file without sidecar | **8.2 s** | **17.5 s** |
  218. **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.
  219. ```shell
  220. flowfast t2i "a pastel toy windmill, plain white background" --out out/wm --name base
  221. flowfast i2i "same object seen from directly behind" --ref out/wm/base.jpg --name back --out out/wm
  222. flowfast views out/wm/base.jpg --views back,left,right --out out/wm
  223. flowfast video "slow turntable rotation, camera static" --start out/wm/base.jpg --out out/wm --upscale 1080p
  224. ```
  225. ## 3D turnaround views
  226. `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.
  227. ```shell
  228. flowfast views assets/windmill.jpg assets/bakery.jpg --views back,left,right --model nano2 --out views
  229. # -> views/windmill_back.jpg, views/windmill_left.jpg, ..., each with a .flow.json
  230. ```
  231. Known views: `back`, `left`, `right`, `front`, `front_left`, `front_right`, `back_left`, `back_right`, `top`. The default prompt template:
  232. > 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.
  233. Override it with `--template "... {view} ..."`. With a custom template you may also pass free-text view names.
  234. **Measured:** 8 game-asset concepts × back/left/right = 24 images in **2 min 38 s**, 24/24 OK, 0 credits.
  235. **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.
  236. ## HTTP API daemon
  237. ```shell
  238. flowfast serve --port 8765 --idle 600 --out /path/to/out
  239. ```
  240. 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.
  241. | method | path | body | returns |
  242. |---|---|---|---|
  243. | POST | `/t2i` | `{"prompt", "model"?, "aspect"?, "count"?, "project"?, "out_name"?, "out_dir"?}` | generate result |
  244. | POST | `/i2i` | `{"prompt", "refs": [path or media_id, ...], ...same...}` | generate result |
  245. | POST | `/views` | `{"assets": [...], "views"?, "template"?, "model"?, "aspect"?, "out_dir"?}` | `{wall_s, ok, failed, images_per_min, results[]}` |
  246. | POST | `/video` | `{"prompt", "start"?, "model"?, "duration"?, "aspect"?, "upscale"?, "out_name"?, "out_dir"?}` | video result (waits for the render) |
  247. | POST | `/upscale` | `{"source": path or workflow_id, "scale"?, "aspect"?, "out_name"?, "out_dir"?}` | upscaled video |
  248. | POST | `/fetch` | `{"workflow_id", "out_dir"?, "out_name"?}` | re-downloaded video |
  249. | GET | `/models` | – | live video catalog |
  250. | GET | `/credits` | – | `{"credits": 100}` |
  251. | POST | `/projects` | `{"title"}` | `{"project_id"}` |
  252. | GET | `/status` | – | browser state, launches, mints, uploads, refs by media id / sidecar / cache, retries |
  253. 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.
  254. ## MCP server
  255. 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:
  256. | tool | arguments |
  257. |---|---|
  258. | `generate_image` | `prompt, model, aspect, count, project_id` |
  259. | `generate_image_from_references` | `prompt, references[], model, aspect, count, project_id, output_name` |
  260. | `generate_views` | `assets[], views[], model, aspect, output_dir, template` |
  261. | `generate_video` | `prompt, start_image, model, duration, aspect, project_id, output_name, upscale` |
  262. | `upscale_video` | `source, scale, aspect, output_dir, output_name` |
  263. | `list_video_models`, `get_credits` | – |
  264. | `create_project` | `title` |
  265. ## Python API
  266. ```python
  267. import asyncio
  268. from pathlib import Path
  269. from flowfast import Engine
  270. async def main():
  271. eng = Engine(out_dir=Path("out"), max_parallel=8, idle_shutdown_s=0)
  272. try:
  273. base = await eng.t2i("a pastel toy windmill, plain white background", model="nano2", out_name="windmill")
  274. mid = base["images"][0]["media_id"]
  275. await eng.i2i("same object seen from directly behind", [mid], model="nano2", out_name="windmill_back")
  276. await eng.views([mid], views=["left", "right"], model="nano2")
  277. await eng.video("slow turntable rotation, camera static", start=mid, out_name="windmill_spin",
  278. upscale="1080p")
  279. print(await eng.credits(), eng.status())
  280. finally:
  281. await eng.aclose()
  282. asyncio.run(main())
  283. ```
  284. | method | does |
  285. |---|---|
  286. | `t2i(prompt, *, model, aspect, count, project, out_dir, out_name, download)` | text-to-image |
  287. | `i2i(prompt, refs, *, ...)` | image-to-image; `refs` = paths and/or media ids |
  288. | `views(assets, *, views, template, model, aspect, out_dir, project)` | N assets × M views, parallel |
  289. | `video(prompt, *, start, model, duration, aspect, project, out_dir, out_name, upscale, timeout_s)` | t2v / i2v, waits for the render |
  290. | `upscale(source, *, scale, aspect, out_dir, out_name)` | 1080p version of a clip (mp4 path or workflow id) |
  291. | `fetch_video(workflow_id, *, out_dir, out_name)`, `models()` | re-download a clip; live catalog |
  292. | `upload(path_or_media_id, *, project)` | → `(media_id, filename)`; cached, sidecar-aware |
  293. | `credits()`, `create_project(title)`, `status()`, `aclose()` | |
  294. Lower level: `flowfast.wire.FlowWire` (raw RPCs) and `flowfast.minter.Minter` (token page).
  295. ## Models, aspects, costs
  296. Images:
  297. | alias | Flow wire name | t2i time | i2i time | credits (tier 1) |
  298. |---|---|---|---|---|
  299. | `nano2-lite` | `HARBOR_SEAL` | ~7 s | ~7–9 s | 0 |
  300. | `nano2` (Nano Banana 2.1) | `BELUGA` | ~17 s | 20–70 s | 0 |
  301. | `nano-pro` (Nano Banana Pro) | `GEM_PIX_2` | ~18 s | – | 0 |
  302. * 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.
  303. * Image sizes: `1:1` 1024×1024 · `16:9` 1376×768 · `9:16` 768×1376 · `4:3` 1200×896 · `3:4` 896×1200.
  304. 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).
  305. ## How it works
  306. ```
  307. caller (CLI / HTTP / MCP / Python)
  308. │
  309. ▼
  310. Engine ────────── httpx ─────────► flow.google.com/_/AiSandboxAngularFrontend/data/batchexecute
  311. │ jHPbke create project nzlxg credits
  312. │ maseQ upload image HTrJv video model catalog
  313. │ ogiZ0b generate image(s) YhhmEf submit t2v
  314. │ eb1hJf submit i2v jwpduf video status poll
  315. │ p0UkFb upscale video as29s media record (signed URL)
  316. │ flow-content.google signed image / video download
  317. │
  318. └─► Minter: ONE headless Chrome page (gflow-cli's profile)
  319. - loads one Flow project page once (that page carries recaptcha/enterprise.js)
  320. - per request: grecaptcha.enterprise.execute(siteKey, {action}) ~0.14 s
  321. - hands its live cookies to httpx
  322. ```
  323. * **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)).
  324. * **Tokens are single-use with a ~2 min lifetime.** flowfast mints one right before each call: `UPLOAD_IMAGE`, `IMAGE_GENERATION` or `VIDEO_GENERATION`.
  325. * **One armed page serves every project**, so the browser never navigates again after start-up.
  326. * **Uploads are cached** (by content hash + project), and parallel callers share one upload.
  327. * Generations run **concurrently** (default 8 in flight). Token minting is serialized, but takes only ~0.14 s.
  328. * The browser starts lazily on the first call. In the daemon it closes after `--idle` seconds without work and relaunches automatically.
  329. ## Reliability: retries and errors
  330. * **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.
  331. * **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.
  332. * `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.
  333. * A stale page token (`at`, HTTP 400/401) is refreshed once automatically.
  334. * The token page waits until `grecaptcha.enterprise` has fully loaded before the first mint.
  335. * In `views`, one failing (asset, view) is reported in `results` and does not stop the batch.
  336. ## When it breaks: compare with gflow-cli
  337. 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:
  338. * an RPC returns an error code (`[3]` invalid argument, `[5]` not found) for a call that used to work;
  339. * a parse error, `no generation record`, or an empty result;
  340. * the token page cannot find the reCAPTCHA site key;
  341. * a model name is rejected, or a download returns HTML instead of an image or mp4.
  342. **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:
  343. 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).
  344. * gflow-cli works but flowfast does not → the wire format changed. Go on with step 2.
  345. * Both fail → it is the account or session (`gflow auth login`), or a Flow outage.
  346. 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:
  347. | flowfast part | where gflow-cli keeps it |
  348. |---|---|
  349. | 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`) |
  350. | image model names (`MODELS`) | `data/models.py`, `api/transports/migrated_composer.py` |
  351. | video model keys, durations | `api/transports/migrated_composer.py` (`VIDEO_MODEL_MENU_LABELS`, key comments), `flowfast models` (live) |
  352. | video upscale (`upscale_video`) | `api/transports/migrated_video_upscale.py` (it clicks the menu; the RPCs it watches are `p0UkFb` and `jwpduf`) |
  353. | profile location, Chrome channel (`engine._gflow_profile`) | `paths.py`, `profile_store.py`, `browser_manager.channel_for_profile` |
  354. | video download URL | `api/transports/migrated_recover.py` |
  355. 3. **Capture what the web app sends now.** gflow-cli can record a HAR of a real run:
  356. ```shell
  357. GFLOW_CLI_HAR_PATH="$PWD/poc/har/new.har" gflow-cli video t2v "test" --json
  358. ```
  359. (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).
  360. 4. **Fix `flowfast/wire.py`** (payload shapes, rpc ids, model names) and record the new shape in `poc/NOTES.md`.
  361. 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.
  362. ## Troubleshooting
  363. | symptom | cause / fix |
  364. |---|---|
  365. | `SignedOut: app shell carries no 'at' token` | The profile session expired. Run `gflow auth login`. |
  366. | gflow-cli says *Profile locked* | A flowfast daemon / MCP server / CLI run holds the profile. Stop it. |
  367. | `no gflow-cli profile to use` | No profile found. Run `gflow auth login`, or set `FLOWFAST_PROFILE_DIR`. |
  368. | `... [5]` on generate | Unknown model name or media id (NOT_FOUND). |
  369. | `... [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). |
  370. | `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`. |
  371. | `reCAPTCHA not ready after 20s` | The project page did not load (network or sign-in). Retry; check `gflow auth status`. |
  372. | video download failed | The clip still exists: `flowfast fetch <workflow_id>` (free). |
  373. | upscale: `got (1280, 720), not 1080p` | Flow returned the original instead of the upscale. Re-run; it is free. |
  374. | HTTP 429 / 503 | Throttled. Lower `--parallel` and wait. |
  375. ## Limitations
  376. * 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`).
  377. * 9:16 video and 9:16 upscale use the catalog's aspect enum, but have not been verified with a render.
  378. * Parallelism above 8 has not been tested.
  379. * The wire format is reverse-engineered from build `boq_labs-ai-sandbox-frontend_20261111.08` and can break on any Flow deploy.
  380. * Reference images are uploaded unscaled.
  381. * Long-running behaviour (cookie rotation over hours or days) is not measured. The engine re-reads cookies every 5 minutes.
  382. * It uses private, undocumented Google endpoints with your own account, and is subject to Flow's terms.
  383. ## Project layout
  384. ```
  385. flowfast/
  386. wire.py Flow batchexecute RPCs over httpx (no browser): images, video, upscale, catalog, downloads
  387. minter.py the one headless page: reCAPTCHA tokens + live cookies
  388. engine.py orchestration: lazy start, session project, upload cache, sidecars, retries, views, video
  389. api.py FastAPI daemon (flowfast serve)
  390. mcp_server.py MCP stdio server (flowfast mcp)
  391. __main__.py CLI (flowfast)
  392. pyproject.toml package + `flowfast` command (uv tool install --editable .)
  393. bench/
  394. run_tests.py image test & benchmark harness (T1-T19); raw output -> bench/out/ (not committed)
  395. video_test.py live video test (t2v + i2v + upscale); costs ~14 credits
  396. poc/
  397. NOTES.md captured wire map (rpc ids, payload shapes, reCAPTCHA actions)
  398. video_models.txt Flow's video catalog as captured
  399. REPORT.md test report with all measurements
  400. .mcp.json MCP config for Claude Code
  401. LICENSE MIT
  402. ```
  403. ## Credits and license
  404. * **[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.
  405. * 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 in

Free to use. If it’s helped, pass it on.