
gflow
- GitHub stars
- 404
Install
/plugin install gflow@gflow-cliRun it inside Claude Code after adding the marketplace with /plugin marketplace add ffroliva/gflow-cli.
Contents
Discovered from sourceSkills 2
gflow-cli skill
gflow-cli is a Python CLI that drives Google Flow — Veo (T2V/I2V) and Imagen / Nano Banana — from the terminal by automating the real Flow web UI in a headed Chrome session (Playwright), not by bypassing it. Source: https://github.com/ffroliva/gflow-cli. Canonical command reference: docs/USAGE.md.
When to invoke this skill
The user wants to:
- Generate one or many Veo videos from text prompts (T2V) or from initial frame + motion prompt (I2V)
- Generate one or many Imagen / Nano Banana images from text (T2I) or from prompt + reference images (I2I)
- Build a batch pipeline for video generations
- Create a reusable, project-scoped Flow Character (a named subject with reference images, optional voice + personality) for consistent subjects across generations (
gflow character) - Compose ordered clips into a scene and optionally render a credit-free server-side extended video (
gflow scene) - Stitch a multi-clip story where each clip is seeded by the previous clip's last frame (
gflow video chain) - Use their Flow credits via script instead of clicking through the UI
- Automate Flow inside a content pipeline, AI video production stack, or research project
Do NOT use this skill when:
- The user wants production-grade reliability with SLAs — recommend the official Gen AI SDK instead.
- The user asks about audio, music, or anything outside Flow's video/image surface — wrong tool.
Prerequisites
Before any gflow-cli invocation, verify:
- Python 3.11+ is available (
python --version). - uv is installed (
uv --version). If not, install:curl -LsSf https://astral.sh/uv/install.sh | sh(or Windows equivalent from https://docs.astral.sh/uv/). - gflow-cli is installed OR available via uvx:
- Quick:
uvx --from gflow-cli gflow --help(no install) - Persistent:
uv tool install gflow-cli && gflow --help
- Quick:
- Playwright Chromium has been downloaded once:
uvx --from gflow-cli playwright install chromium(~150 MB). - A signed-in profile exists:
gflow auth statusshould printFlow session verifiedand exit 0 (it probes the live session, with no credits, and may open a short-lived headless browser; exit 1 means dead or missing session). If not, rungflow auth loginand walk the user through the one-time browser sign-in. - The user has Flow access — any Google account with Flow rolled out works. If
gflow image uploadreturns 403, missing Flow access is the cause.
Core commands
# Auth (one-time)
gflow auth login # opens Chromium, user signs in
gflow auth status # confirms session
gflow auth renew [--profile NAME | --all] [--json] # headless cookie refresh, no re-login
gflow auth # bare: list profiles or trigger first login
gflow auth logout # delete a saved session
# Veo video-credit balance (read-only; image models use separate daily quotas).
# Reads the balance Flow itself shows: directly (no browser) when the saved session is accepted,
# otherwise in the profile's browser. GFLOW_CLI_WIRE_READS=0 always uses the browser; the
# direct read is also off by default on macOS and skipped while any proxy is configured.
# Exit 4/6 = Flow is throttling the account (429/503): wait, do not retry in a loop.
# (Under the opt-in GFLOW_CLI_EXIT_CODES=2 these are 40/42; see docs/ERRORS.md.)
# Exit 3 = sign-in page (fix: --refresh); 31 = /about or no balance reply (NOT an auth
# problem, do not loop on login); 11 = profile in use; 7 = unrecognised reply. Tier fields are null.
gflow credits user [--profile NAME] [--refresh] [--json]
gflow credits list [--refresh] [--json] # all saved profiles; --refresh renews signed-out sessions
# What this gflow can drive (no call to Flow; yes/no/partial/unknown per key, notes on partial).
# cancel.server and idempotent_submit are "no": a submitted generation runs and may still be charged.
# MCP twin: resource capabilities://self (same document; generation is "no" on a no-spend server). Keys: docs/CAPABILITIES.md
gflow capabilities [--json]
# Image generation (Imagen / Nano Banana)
gflow image upload <path> # → asset UUID + dimensions
gflow image t2i "<prompt>" [--model {nano2|nano2-lite|nano-pro|image4}] \
[--aspect {9:16|16:9|1:1|4:3|3:4}] \
[-n 1..4] [--out DIR]
gflow image i2i "<prompt>" --ref PATH_OR_UUID [--ref ...] [...same as t2i]
gflow image generate "<prompt>" [--ref ...] [...] # bridge: no --ref -> t2i, --ref -> i2i (#1193); --json adds "mode"
gflow image upscale <mediaId> --scale {2k|4k} [--project ID] [--out DIR] # 4K is Ultra-only
gflow image batch <manifest.tsv|manifest.json> [-n 1..4] [--aspect ...] [--out DIR] # shared project, up to 5 prompts; refuses any row ref (exit 11, like any manifest error)
gflow run --config <batch.json> [--project ID] # JSON image batch; a row's "ref" may be "batch:N" (an earlier
# row's image, in place, no upload) or a local file (uploaded once);
# --project (or "project" in the config) reuses an existing project
gflow run --config <batch.json> --project ID --resume # skip rows already on disk + in the catalog (#934)
# For accounts Flow serves flow.google.com (#639), t2i, i2i, and upscale are ported (a project is
# created when --project is omitted, #864): i2i accepts local --ref files only, all
# five aspects. Images take a character by name (@Name, or --reference-entity with
# --reference-entity-name; #723). UUID references, an entity id without a name,
# Imagen 4 (image4), image batch, and characters on t2v/i2v are refused there (exit 36);
# local-file video r2v takes --reference-entity with --reference-entity-name (#723).
# `gflow video extend` runs there one segment per call (--project required); -n > 1,
# --scene/--resume-from, --seed and an --aspect other than the source clip's exit 36.
# An agent-only composer (#799) is different: t2i and t2v only;
# i2i, i2v, r2v and character references exit 36 there, after up to
# three free page reloads in case Flow serves the classic composer (#1142).
# A run without --project creates a new Flow project, unless GFLOW_CLI_PROJECT=<id> is set
# (#1039): t2i/i2i/t2v/i2v/r2v, `gflow run` and the MCP generate tools then use that
# project. Set it once when looping, instead of leaving one project per call.
# Video generation (Veo 3.1)
gflow video t2v "<prompt>" [--project ID] [--model ...] [--duration 3..15] [--resolution 360p|720p] [--out-dir DIR] [--aspect ...] # --resolution: Omni models only; without --project a project is created first, on either host (#864); durations: 4/6/8 Veo, 4/6/8/10 omni-flash, 3-15 omni-1.2-flash
# Flow retires omni-flash, veo-fast and veo-quality on 2026-12-05 (`retires_on` in `gflow models --json`): use veo-lite or omni-1.2
gflow video i2v --initial-frame <image|media-UUID> "<prompt>" [--end-frame <image>] [--out-dir DIR] [...same as t2v] # UUID = in-project asset, no re-upload (#287; pair with --project); --end-frame caps omni-1.2-flash at 10s
gflow video generate "<prompt>" [--initial-frame F | --ref IMG] [...] # bridge: none -> t2v, frame -> i2v, --ref -> r2v; frame AND --ref = exit 2 (#1193)
gflow video upscale <mediaId> --scale {1080p|720p|270p} [--project ID] [--out DIR] # 1080p = Full HD, 720p = original, 270p = GIF; Flow lists 1080p for some models only (exit 22 otherwise)
# `gflow video` has no `batch` subcommand — that stub never worked and was
# removed. For multi-clip runs, loop `gflow video t2v`/`i2v` from the shell.
gflow video chain <manifest.jsonl> [--out-dir DIR] [--dry-run] \
[--max-links N] [--resume-from N] # last-frame I2V chaining; veo models only
# --out-file out/clip.mp4 writes link i to out/clip_<i>.mp4 (#1293)
# Characters (reusable, project-scoped subjects)
gflow character create --project <id> --name "<name>" --face-prompt "<prompt>" \
[--body-prompt "<prompt>"] [--voice <id>] [--personality "<text>"] \
[--model {nano2|nanopro}]
gflow character list --project <id>
gflow character show <character-id> --project <id>
gflow character rm --project <id> (--id <character-id> | --name "<name>") [--yes] # delete (FREE)
gflow character voices # list the Gemini voice catalog
# Scenes (Add Clip / compose ordered clips)
gflow scene create --project <id> <clip-id> [<clip-id> ...] \
[--out-file extended.mp4] # --out-file = credit-free server-side concat
gflow scene show <scene-id> --project <id>
# Agent instructions (project brief cards, credits-free setup) — --project is REQUIRED
gflow instructions add TITLE --text TEXT [--ref REF]... --project ID [--disabled]
gflow instructions list --project ID [--json]
gflow instructions enable (TITLE | --id ID) --project ID
gflow instructions disable (TITLE | --id ID) --project ID
gflow instructions rm (TITLE | --id ID) --project ID
gflow instructions apply FILE --project ID # declarative full-sync (TOML/JSON)
gflow instructions toggle-mode (--on | --off) --project ID # toggle master agent switch
# Discover every command, its params and whether it spends credits (stable JSON, #1203)
gflow --help --json # also: gflow <group> [<cmd>] --help --json
# Keeping gflow-cli current (other commands show a banner when a newer release exists)
gflow update [--check] [-v|--verbose] [--json] # upgrades via uv tool / pipx / pip; source installs refused (exit 11); on Windows pip, exit 11 also when another gflow process holds a launcher (nothing changed: close it, retry); a Windows pip install at <=0.99.0 upgrades once by hand: close every gflow process, then `<venv>\Scripts\python.exe -m pip install --upgrade gflow-cli` (with any installed extras, e.g. `"gflow-cli[patchright]"`; docs/USAGE.md#gflow-update); -v streams the installer output
gflow docs [TOPIC] [--search TERM] [--json]
# Usage statistics and weekly telemetry (local counters; upload after interactive notice)
gflow data stats [--weeks N] [--json]
gflow telemetry on
gflow telemetry off [--delete]
gflow telemetry status [--json]
gflow telemetry show
# Abort a queued job (local only; MCP twin: tasks/cancel). No --profile: task ids are global
gflow cancel TASK_ID [--json] # not yet submitted -> cancelled, exit 0, nothing charged;
# already submitted -> abandoned, exit 22: Flow cannot cancel it,
# it may still be charged (cancel.server: no)
Every subcommand accepts --profile <name> (per-subcommand, not global) to drive multiple Google accounts side-by-side.
Recipes
Single image (most common)
gflow image t2i "a hot air balloon over Tokyo at sunrise" --aspect 16:9
Image fan-out (4 variants in parallel)
gflow image t2i "variations of a minimalist fox logo" -n 4 --aspect 1:1 --out ./logos/
Image-to-image with a local reference
gflow image i2i "make it cinematic, golden hour" --ref hero.png
Image-to-image with an already-uploaded asset UUID (no re-upload)
UUID=$(gflow image upload hero.png | awk '/Asset UUID:/ {print $3}')
gflow image i2i "stylize this asset" --ref "$UUID"
Single clip from initial frame
gflow video i2v --initial-frame ./input.png "Slow cinematic push-in, soft golden light at sunset" --out-dir outputs
Batch from a directory of inputs (bash)
There is no manifest-driven video batch command — that stub never worked and
was removed. Loop gflow video t2v/i2v from the shell instead:
mkdir -p out
for img in ./inputs/*.png; do
name=$(basename "$img" .png)
gflow video i2v --initial-frame "$img" "Cinematic push-in" --out-dir out
done
New-Item -ItemType Directory -Force -Path out | Out-Null
Get-ChildItem ./inputs/*.png | ForEach-Object {
gflow video i2v --initial-frame $_.FullName "Cinematic push-in" --out-dir out
}
Create a reusable Character for consistent subjects
# A Character is a named, project-scoped subject reused across generations.
gflow character create --project "$PROJECT_ID" --name "Joaquim" \
--face-prompt "weathered fisherman, grey beard, kind eyes" \
--body-prompt "tall, broad-shouldered, wearing a navy wool sweater" \
--voice <voice-id> --model nano2
gflow character voices # discover valid --voice ids first
gflow character list --project "$PROJECT_ID"
See docs/CHARACTER.md for the full domain model, wire protocol, and the crash-recoverable persist-before-spend saga.
Compose clips into an extended video (credit-free)
# Concatenate ordered clips server-side via runVideoFxConcatenation — no local ffmpeg, no credits.
gflow scene create --project "$PROJECT_ID" "$CLIP_A" "$CLIP_B" --out-file extended.mp4
Chain clips by last frame (story stitching)
# manifest.jsonl: one JSON object per line. Link 0 = t2v; later links = i2v seeded by the
# previous clip's last frame. Each link is a pending video operation; credit
# use varies by model/duration/tier — check Flow. veo models only.
gflow video chain ./story.jsonl --out-dir ./out/ --dry-run # preview the plan first
gflow video chain ./story.jsonl --out-dir ./out/ # then run for real
Sync instructions and generate (3-layer pipeline)
# 1. Discover project ID from Flow editor URL (.../project/<id>/...) or create one.
# 2. Set up the brief cards (credits-free setup).
gflow instructions apply brief.toml --project 6b714c4e-...
# 3. Generate using that project context (steers via reasoning path).
gflow image t2i "a bicycle" --project 6b714c4e-...
Use as a Python library
import asyncio
from pathlib import Path
from gflow_cli.api.client import FlowApiClient
from gflow_cli.paths import profile_dir
async def make_clip(image: Path, prompt: str, out: Path) -> None:
async with FlowApiClient(profile_dir=profile_dir("default")) as client:
project = await client.create_project(title="gflow-cli demo")
asset = await client.upload_image(image, project.project_id)
op = await client.generate_video(
project_id=project.project_id,
prompt=prompt,
start_asset=asset,
aspect="9:16",
)
# Poll op.workflow_id with client.poll_video_status(...) and
# client.download_video(...) when status reaches succeeded.
asyncio.run(make_clip(Path("in.png"), "Push-in", Path("out.mp4")))
Layered Instructions Pipeline
The gflow-cli supports a 3-layer pipeline for persistent generation context (Agent Mode brief cards):
- Layer 1 (Setup - credits-free): Set up the project brief cards using
gflow instructions addorgflow instructions apply. - Layer 2 (Generate): Run generations targeting that project with
--project <id>. Enabled brief cards are automatically resolved and folded into the prompt via the agent's reasoning path. - Layer 3 (Compose): Scene-level composition overrides via
movie.toml[[scene.instructions.card]]or[scene.instructions] disableblocks.
Constraints & Rules:
- Discover Project ID First: Persistent cards require a real project. Discover the project ID from the Flow browser editor URL (
.../project/<id>/...) or create one. - DO NOT use the ephemeral
-i / --instructionoption for anything you want to reuse; it creates a new card every call. Prefer persistentgflow instructionscards. - Master Switch: Ensure agent mode is toggled on (
gflow instructions toggle-mode --on) for cards to steer output.
Common errors and fixes
| Error | Cause | Fix |
|---|---|---|
No session for profile 'default' | First run, no auth | gflow auth login |
403 Forbidden from upload / generate | Account doesn't have Flow access | Verify in labs.google/fx/tools/flow |
| reCAPTCHA refuses to mint a token (headless detected) | Google bot-detection | Set GFLOW_CLI_HEADLESS=false and re-run; a headed window passes detection. With --json, a mint failure has type …/errors/recaptcha-mint and exits 1; re-run only when retryable is true |
Playwright Executable doesn't exist | Chromium not downloaded | uvx --from gflow-cli playwright install chromium |
| Generations all fail with the same UUID | Stale Flow session | gflow auth login again to refresh cookies |
| Quota exceeded | Burned through monthly credits | Wait for reset, or upgrade subscription |
| Every page step times out, but auth/HTTP calls work | Network reaches Google only through a proxy; the browser ignores HTTPS_PROXY | Set GFLOW_CLI_BROWSER_PROXY=http://host:port (no credentials: a password-protected proxy is refused, exit 11) |
Exit 7 RpcResponseUnavailableError ("outcome unknown") | A create/rename/upload was sent but its result was never seen | Do NOT re-run blindly: check the project on flow.google.com first (a re-run can duplicate), then pass --project <id> |
| No progress lines any more | Default log level is WARNING since v0.88.0 | GFLOW_CLI_LOG_LEVEL=INFO or -v |
| Any error, unsure whether it cost anything | Every error envelope (--json, MCP) carries charged (yes/no/maybe) and next_action | Follow next_action: retry is safe; reconcile means check the project in Flow before re-running (a billed request is never resent); reauth means sign in again. See docs/ERRORS.md |
Important constraints
- Video costs Flow credits. Video generation draws down the balance shown by
gflow credits; image generation uses separate per-model daily quotas. Confirm before running batches. - Not for production-grade SLAs. gflow-cli reverse-engineers a private Google API. It can break without notice. For production, use the official Gen AI SDK.
- Don't share auth profiles. The Playwright profile dir lives at the per-OS user-data location (Windows:
%LOCALAPPDATA%\gflow-cli\profile_*; macOS:~/Library/Application Support/gflow-cli/profile_*; Linux:~/.local/share/gflow-cli/profile_*) and contains Google session cookies — treat as secrets. - Same profile can't run in parallel. Chromium refuses two persistent contexts on the same profile dir; use different
--profilenames for parallel work. - Respect Google's Generative AI Prohibited Use Policy. Don't generate content that would get the user's Google account banned.
Known agent failure modes
Documented errors agents commonly make — negative examples for the SkillOpt training loop:
| Mistake | Correct behaviour |
|---|---|
gflow video create | gflow video generate (alias gen; mode read from the inputs), or the mode verb itself: gflow video t2v (text→video) / gflow video i2v (image→video) |
Passing file path to -o/--output or --output DIR | -o/--output selects output format (json|table|id); --out-file PATH is an explicit FILE path (single-prompt only); use --out DIR (image) / --out-dir DIR (video) for directory output. |
An absolute MCP out_file / out_dir outside the output dir, or a path as MCP profile | MCP tools write only inside GFLOW_CLI_OUTPUT_DIR (v0.92.0+): pass out_file relative to it; anything else returns 400 Invalid Output / Invalid out_dir. profile is a plain name (400 Invalid Profile). The CLI --out-file is unchanged |
gflow auth bare or gflow login to sign in | gflow auth login — bare gflow auth only lists profiles |
gflow auth refresh (doesn't exist), or gflow auth login as the first move on an expired session | gflow auth renew renews an expired session headlessly with no sign-in; gflow auth login only when renew reports the session could not be renewed (revoked) |
playwright install or playwright install --all | uvx --from gflow-cli playwright install chromium (Chromium only, ~150 MB) |
Running two generations on the same --profile in parallel | Use different --profile names — Chromium refuses two persistent contexts on the same dir |
GFLOW_CLI_HEADLESS=true to fix reCAPTCHA failures | GFLOW_CLI_HEADLESS=false — headless mode causes bot-detection, not prevents it |
Calling gflow image upload again for an already-uploaded UUID | Pass the UUID directly to --ref UUID (i2i) or --initial-frame/--end-frame UUID (i2v, with --project) — no re-upload needed |
--model imagen / --model quality / --model high | --model image4 (Imagen 4, no longer in Flow's menu), --model nano-pro (Nano Banana Pro), --model nano2 (Nano Banana 2.1; nano2.1 also works). gflow models lists each model's Flow name; gflow models show <alias> prints one model's limits |
Python: client = FlowApiClient(...) then method calls | Must use async with FlowApiClient(...) as client: — it's an async context manager |
Python: from gflow_cli import FlowApiClient | from gflow_cli.api.client import FlowApiClient |
gflow video t2v/i2v/r2v with an unported UUID/entity reference or model on an account served flow.google.com (exit 36) | Pass local files instead — migrated hosts support video t2v, local-file i2v/r2v, single-segment video extend, and image t2i/i2i (local refs, a same---project catalogued UUID ref (#995), plus @Character mentions on images, #723), and r2v with a named character (--reference-entity + --reference-entity-name, #723) only — and an agent-only composer (#799) image t2i and video t2v only; exit 36 is non-retryable, GFLOW_CLI_FLOW_HOST=labs.google is the kill switch (see USAGE § gflow video t2v / i2v / r2v and image sections) |
Telling a user on flow.google.com whose run exits 25 to retry, switch profile or pass --ui-mode classic | On an agent-only composer gflow drives image t2i and video t2v through the agent (#799); exit 25 there means the agent went off-script — a credit confirmation quoting more than asked (rejected, nothing approved) or one whose count gflow cannot read, a second confirmation, more results than asked, or a turn that made nothing (retryable: false). Read the envelope's detail; rephrase the prompt rather than re-running blind, and check the project first — a video may still be rendering. Other forms on that composer exit 36. Exit 25 on labs.google IS the retryable A/B cohort — check the host before advising |
Suggesting a native batch subcommand under gflow video | It doesn't exist — that stub never worked and was removed. Loop gflow video t2v/i2v from the shell for multi-clip runs (gflow image batch manifest.tsv|json is the real, working batch command, but it's image-only) |
Disclaimer
gflow-cli is not affiliated with Google. Reverse-engineered; may break when Google changes Flow's private API. Read the DISCLAIMER before deploying in any sensitive setting.
video-production
Core principle: control is everything. Every guard-rail you put in front of the engine is drift you do not pay for later. Lock the shape, the cast, the location and the words before spending, then gate every clip on evidence rather than impression.
This skill covers composing gflow into a finished video. It does not restate the command surface — that is the gflow-cli skill, which owns per-command syntax, flags and single-shot recipes. Load that one for "how do I call t2v", this one for "how do I turn a script into a film that holds together".
How to read the claims in this skill
Every non-obvious statement is tagged. This is one calibrated approach, not the only one. Other people drive this engine with techniques not tracked here; absence from this document means untested, never forbidden.
| Tag | Meaning | You may |
|---|---|---|
| [CONSTRAINT] | the engine refuses, fails, or silently drops the request | not deviate |
| [CALIBRATED] | measured here, sample size and conditions stated | deviate with evidence |
| [CONVENTION] | one shape that works; alternatives exist | deviate freely |
| [UNEXPLORED] | known to exist, not tested here | try it, then add a task |
When NOT to use this skill
A single clip with no continuity requirement, one image, or a pure command-syntax question — use the gflow-cli skill. Editing or grading existing footage — this is generation, not post. Any engine that is not Flow.
Prerequisites
Everything gflow — Python 3.11+, uv, an installed gflow, Playwright Chromium, a signed-in profile, Flow access — belongs to the gflow-cli skill's Prerequisites. Run its checks; do not restate them.
This skill adds three:
ffmpegandffprobeon PATH, 5.0 or newer —ffmpeg -version. The assembly step uses-fps_mode, which does not exist before 5.0.- An ffmpeg carrying
libassandlibfreetype— the same banner lists enabled libraries. Burned subtitles (subtitles) and title cards (drawtext) are absent from minimal or "essentials" builds. Usual Windows trip. faster-whisper, only if you want the transcript gate —python -c "import faster_whisper". Nothing in gflow installs it. First run pullsbase.en, ~75 MB, once. Without it you lose the word-hit check and keep every other gate.
clip_qa.py, beside this file, needs only ffmpeg, ffprobe and the standard library — so the fluidity, lip-sync and A/V-drift gates still run where the transcript gate cannot.
Step 1 — intake, before anything else
The plan changes completely with the answers. Ask, or read them from the brief; do not assume.
| Question | Why it changes the plan |
|---|---|
| What is the deliverable, and who watches it? | a rehearsal reference tolerates flaws a client cut does not |
| Does anyone speak on camera? | decides dialogue budgeting, lip-sync gating, and i2v-vs-r2v |
| Is audio generated, added later, or discarded? | Veo always generates audio [CONSTRAINT] — see below |
| Captions: none, burned-in, or a sidecar file? | burned-in needs libass and a timing source |
| One location or several? How many camera angles each? | drives the plate-chaining work in consistency.md |
| Recurring people? How many in frame at once? | one face-bearing reference per generation [CONSTRAINT] |
| A prop that must not change? | needs its own sheet with a scale anchor |
| Aspect, total length, credit ceiling | 16:9 or 9:16; clips are 4/6/8, 10 on omni-flash, or 3–15 on omni-1.2-flash (≤10 with an end frame) |
| One-off, or a repeatable pipeline? | decides the production shape in composition.md |
Veo always generates audio [CONSTRAINT]. There is no silent mode and omitting sound from the prompt does not produce silence. A "silent" montage returns invented room tone under every shot. If the audio is unwanted, strip it at assembly (-an) rather than hoping for a quiet clip.
Step 2 — check the host, or the whole plan is dead
Load https://labs.google/fx/tools/flow/project/<id> in the profile's Chrome and read the final URL.
| Lands on | Lane | What runs there |
|---|---|---|
labs.google/fx/… | A, full | everything |
flow.google.com/project/… | B, partial | video t2v --project, video i2v --initial-frame <local file> --project, video r2v --ref <local file> --project (ported in v0.70.0, #683; a named character with --reference-entity + --reference-entity-name since v0.91.0, #723), and image t2i / image i2i with local --ref files (#639), and video extend for ONE segment (#882; -n > 1, --scene/--resume-from, --seed and an --aspect other than the source's exit 36). character create worked there from v0.70.0 until its labs route was retired: since 2026-10-14 it exits 7 on a profile served flow.google.com. Everything else — image batch, multi-segment extend, scene create, movie run, r2v by @Name or --reference-entity, i2v by media UUID / @Name, and Imagen 4 — exits 36 [CONSTRAINT]. A local --end-frame IS ported (start+end interpolation, #639) |
Lane B grows as forms are ported, so confirm the row rather than trusting it: the
maintained list is CONFIGURATION § GFLOW_CLI_FLOW_HOST
and the #639 entry in KNOWN_ISSUES. Exit 36 on a form the table
says is ported is a regression worth filing, not the environment.
An unported command on lane B exits 36, non-retryable, with a message naming the
migration. A RecaptchaError instead means one of two other things: on gflow ≤ 0.68.0 the
migration guard ran after the reCAPTCHA mint on the image path, so image commands died
as exit 1 there (gflow-cli#673, fixed); on any build, a RecaptchaError right after
gflow auth login is the cookie harvest keyed on the old host (gflow-cli#644). Either
way the first move is the same: read the final host URL before anything else. Do not
plan entities or plates before this check.
There is a gflow project create [CONSTRAINT]. gflow project create --name <piece> --json > out.json, redirected to a file, never piped through head, which truncates the process before the JSON prints. Do not mint a project by burning a placeholder generation, and do not scrape the id from a browser URL.
Step 3 — the production shape
Pick one; each has a worked command chain in composition.md.
| Shape | When | Driver |
|---|---|---|
| One-off sequence | a scene, an audition, a montage | shell, clip per beat |
| Manifest-driven | a script that will be re-run as it is edited | movie run with a stable scene id per slot |
| Continuous shot | one camera move longer than 8 s | video extend |
| Deliberate cut with continuity | a new angle that must match the last frame | video chain |
| Assembly only | clips already exist | scene create (free) |
Step 4 — lock the assets before spending
4a. The identity resolution ladder — deterministic, and you record the rung
A person in a shot is anchored by exactly one of these. Take the highest rung the host and path allow, and write down which rung you used and what blocked the one above. This is not a preference order, it is the production record: a film whose log does not say how each shot was anchored cannot be debugged when a face drifts.
| # | Anchor | What it carries | Use when |
|---|---|---|---|
| 1 | Character entity — @Name or --reference-entity <id> | face and wardrobe and voice, server-side, durable | always, unless a rung-1 blocker is recorded |
| 2 | That entity's own generated plate — --ref <its portrait or body crop> | face and wardrobe, as a flat image | rung 1 refused by the host/path |
| 3 | A plate cut from an approved take — --ref <frame> | face, plus that take's grade, light and artefacts | no entity exists |
| 4 | Prose canon only | a type, never an identity | nothing else is available |
Rung 4 does not hold a person. Each generation invents someone new who merely matches the description. Two shots on rung 4 are two different actors. Never plan a multi-shot piece on it and never let it be the silent default.
Rung 3 carries contamination. v1's opening take came back with 72 px letterbox bars and its plate carried those bars into every shot that referenced it. A rung-2 plate is generated clean by the character editor; a rung-3 plate is only as clean as the take it was cut from.
Descending a rung is a decision that gets written down, in production.json next to the
shot, naming the blocker. "I used an image" is not a record; "rung 2, because
--reference-entity on t2v exits 36 on this host (#716)" is.
Written from a run that skipped its own ladder. On 2026-09-07 a five-shot film created two real character entities and then anchored every shot on rung 2, because gflow refuses entity references on the migrated host. The refusal was never questioned — and a $0 probe the same day showed the host takes an entity mention perfectly well (
data-reference-type="entity"with the realentity_id); it is gflow that has not ported the gesture. The run went a rung lower than it had to and recorded it only in passing.
4b. Entity beats media when a name matches both [CONSTRAINT]
Flow's @ picker offers character entities and media assets in one list, and a query
matching both can resolve to either — measured 2026-09-07: the same @Kael returned
reference_type="entity" on one gesture and reference_type="media" (a JPEG that happened
to be named after him) on another. Flow does not rank them.
So you rank them. When a name matches a character and a file, the character wins, and if
you meant the file, reference it by path (--ref <path>) rather than by name. A shot that
silently binds a still image where you asked for a character produces footage that looks
right and drifts on the next cut.
4b-bis. A cast with VOICES — the whole recipe, end to end
A character entity is the only thing that carries a voice. A plate does not: it carries face and wardrobe as pixels, and the engine invents a new voice for every clip. Measured 2026-09-07 on one character across three plate-bound takes: 88 Hz, 103 Hz, 118 Hz — three different actors — against an engine noise floor of 4.3 Hz on an identical prompt repeated three times. No re-shoot fixes that, because nothing in a plate was ever carrying the voice.
So if anyone speaks more than once, you need rung 1. Here is the whole path.
1 — pick the voice before you create anyone. gflow character voices lists 30 presets.
Each has a public sample you can actually listen to, so audition rather than trust the
descriptor — five of the 29 descriptors measured so far disagree with the measured pitch of their own sample (Enceladus, in the catalog since 2026-10-16, has not been measured):
gflow character voices --json
# every voice has: https://gstatic.com/aitestkitchen/voices/samples/<Name>.wav
2 — create the character with the voice bound. Face, body and voice in one call:
gflow character create --project "$PROJECT" \
--name "<UniqueName>" \
--face-prompt "a man, <face description with a GENDER WORD>" \
--body-prompt "<outfit; no print, no logo>" \
--voice "<VoiceName>" \
--personality "<how they behave>" \
--json > cast_<name>.json
Three traps, each measured:
- The name must collide with nothing in the media library. Flow's
@picker searches characters and media together and does not rank them (4b), so an uploadedkael_ref.jpgwins the query@Kaeland your character becomes unreachable by name. Never name a plate after a character;plate_a.png, not<name>_ref.jpg. - A face prompt with no gender word gets a gender chosen for it. This fires on the
prose canon too, not just on
character create— a two-hander whose unbound actor is described without one renders the wrong person. - Keep the
entity_idyourself. Read it from--jsonat creation. Do not plan on recovering it from the catalog afterwards.
3 — attach the character to every shot they appear in.
gflow video t2v "<prompt>" --project "$PROJECT" \
--reference-entity "<entity_id>" \
--reference-entity-name "<UniqueName>" \
--aspect 16:9 --duration 8
One face-bearing reference per generation [CONSTRAINT] — so in a two-hander, bind the person who speaks and carry the other in prose. Getting that backwards is what produced the 88 Hz stranger above: the beat bound the silent actor, so the speaker fell to rung 4.
4 — expect the submit to outlive your patience, and do not read a timeout as a failure.
Flow allows five concurrent generations and throttles per-minute throughput after heavy
daily use, so a queued job routinely outlives gflow's submit-reply budget. An
entity-bound run can exit 9 TransportTimeoutError while the video is rendering
normally — the job is in Flow's queue and will finish. Check the project before you
re-submit, or you will double-spend on a generation you already have. (gflow-cli #723,
#741.)
5 — verify the voice actually landed, relatively. Never assert an absolute band: a character legitimately speaks differently in an action beat than in a quiet one, and the pitch follows the performance. The two sound comparisons are:
- the same character across comparably-staged shots — the medians should sit close
- a bound take against that voice's own public sample — the same neighbourhood
And stage every dialogue beat in still air. An energy gate is not a voicing gate: on this production's own wordless clips the detector reported a confident 145 Hz and 280 Hz with no speech present at all, and periodicity did not separate them either. A beat shot in wind cannot be checked.
4c. A costume is part of the identity, so a costume change is a NEW entity [CONSTRAINT]
A Flow character entity bundles face and wardrobe — the body reference fixes the outfit. There is no wardrobe axis inside one entity.
So a character who changes clothes is two entities sharing a face prompt, with different body prompts, named for the costume state:
Kael_ridge face_prompt=<the canonical face> body_prompt=<dust-brown canvas jacket, sand scarf>
Kael_coat face_prompt=<the same canonical face verbatim> body_prompt=<heavy oiled coat, hood down>
The face prompt must be byte-identical across costume states; only the body prompt moves. Then every scene names the costume-state entity, not the character, and continuity becomes a lookup instead of a hope.
movie.toml refuses the variant shortcut here [CONSTRAINT]. Character.variants is a
Mapping[str, str] and resolve_variant() appends a text delta to the prose appearance
(composition.py:67-80), while the runner creates exactly one entity per character name
(cli_movie.py:589-597). On an identity = "entity" character a variant would change the
words while the entity's body plate kept the original outfit, and the two would argue inside
one generation. The manifest parser therefore rejects variants on an
identity = "entity" character (exit 11, #724): express costume states as separate entries
in the manifest's characters array, each with identity = "entity" and a shared face
prompt. See MOVIE.md for the TOML.
Full method in consistency.md. The rest of the short form:
- People are Flow CHARACTER entities, attached with
--reference-entityor@Name. Identity. - Locations and props have no entity type [CONSTRAINT] — they are images attached per shot with
--ref. Look. - One face-bearing reference per generation [CONSTRAINT]. A second entity, or an entity plus a portrait, returns HTTP 400 reported as a wire-format error. Carry other people as role nouns in prose.
- Multi-angle locations must be chained, not generated in parallel [CALIBRATED] — anchor angle by
t2i, every other angle byi2i --ref <anchor>. Independent calls from the same paragraph produce different rooms. - The reference count picks the model, before quality does [CONSTRAINT]. Caps are per model and the entity counts against the same pool:
omni-flashandomni-1.2-flash7,veo-lite/veo-fast/veo-lite-lp3,veo-quality0 — it accepts no references at all. So a shot carrying any--refor entity cannot useveo-qualityhowever much you want its quality. For a single generation needing references and quality together, that makesomni-1.2(omni-1.2-flash) the pick (omni-flash,veo-fastandveo-qualityleave Flow on 2026-12-05, #1375;gflow modelsshows the date); aveo-litevariant when 3 refs is enough.video chainis the exception [CONSTRAINT] — it refuses both Omni models outright (its i2v is wire-verified for single generations only) and exits with a model/mode incompatibility, so chained links take a Veo 3.1 model and its cap of 3. Full table, image models included:consistency.md. - Attaching by media UUID buys asset identity, never scene coherence.
Step 5 — beat sheet
One row per clip: id, camera setup, action, lines with delivery, duration, model, references.
- Durations are 4/6/8, plus 10 on omni-flash, and every integer 3–15 on omni-1.2-flash (above 10 needs a Google AI plan, else exit 11 before submit; with an end frame at most 10, because Flow drops the end frame above it and bills a start-only clip, #1178) [CONSTRAINT].
--durationrequires an explicit--model; omitted, it bindsveo-lite, which renders no duration control, and exits 2. - ≤ 2.5 spoken words per second [CALIBRATED, 25 clips, one model] — 8 s ≈ 18 words, 10 s ≈ 24. Above it, delivery rushes and the last sentence is cut.
- Never rewrite the script to fit. Split a long speech across beats; the words are the deliverable.
- Two speakers per beat is fine with the order explicit; three is where sync breaks [CALIBRATED].
- One moment per clip. A beat with a second of action inside eight seconds invents material to fill the rest [CALIBRATED].
- Named camera setups and a declared 180° axis: see
consistency.md.
Step 6 — prompt shape
style → setting → geometry → cast → setup → action → dialogue → avoid.
- Never name a film format — "35mm", "IMAX", "film grain" draw a sprocket-hole border or change the medium [CALIBRATED]. Say "full-frame 16:9 image edge to edge" and put border, letterbox and vignette in the avoid list.
- That avoid-list entry is not sufficient on its own [CALIBRATED, 4 clips, veo-quality]. A shot opening "Cinematic close portrait…" returned 72 px letterbox bars top and bottom while carrying "full-frame 16:9 image edge to edge" and "letterbox bars" first in its avoid list. The word cinematic appears to be enough on its own; no format was named. Restating it positively and explicitly — "full-frame 16:9 image filling the entire frame edge to edge, no bars, no border" — returned three consecutive bar-free shots with everything else held constant. Measure it, do not eyeball it:
cropdetectreported nothing on the bar-carrying clip, so check the frame's own dark-row extents instead. A plate cut from a barred clip carries the bars into every shot that references it. - No age words near a person [CONSTRAINT]. One age phrasing failed eight generations running; a relational or role noun passed immediately with everything else held constant. Minors are refused outright.
- Dialogue as prose with the delivery before the words:
NAME says, weary: …. Levers, most to least reliable: volume, emotional state, pace, register, physical condition, accent. - The avoid list holds artefacts only. Negations that name an action do not suppress it — restate positively.
- ~1,100–1,400 characters [CALIBRATED]; longer prompts have returned 400.
- Nothing in frame carries text unless you have a glyph master. Whatever carries text invents text.
Step 7 — trial one beat, then batch in pairs
Generate one clip, run the gates, fix the template, then continue two beats per foreground call [CALIBRATED]. A detached background run lost a clip mid-poll and a template bug repeats once per clip at full price. Never loop a retry into a refusal.
Step 8 — gates
Nothing is accepted on impression. Run clip_qa.py; add the transcript check when speech matters.
python clip_qa.py <clips_dir> # fluidity, lip sync, A/V drift, per clip
python clip_qa.py final.mp4 # the assembled cut
python clip_qa.py --selftest <clip.mp4> # prove the detector before believing it
Directory mode matches exactly [a-z]{2}\d{2}.mp4 — two letters then two digits, e.g.
ka01.mp4. Descriptive names and 0100.mp4 both silently match nothing and report
"no clips matched", which reads like a path error.
On a clip with no speech, run --selftest before acting on a sync verdict [CALIBRATED].
A wordless close-up flagged DRIFT sync=+0.500s r=0.7 — correlation above the 0.3 threshold,
so the gate applied. --selftest on that same clip then failed to recover a known injected
0.2 s shift (saw -0.500s), which disqualifies the reading rather than confirming it. The
detector correlates face-region motion against audio; with only wind on the track there is
nothing for it to lock onto, and it locks onto noise. This is the skill's own listed weak spot
("a lip-sync detector trusted without first proving it against a known delay") reproduced.
| Gate | Threshold | Tier |
|---|---|---|
| Stream lengths on the cut | video and audio within 0.1 s | CONSTRAINT (a mismatch is drift) |
| Speech onset after the cut | ≤ 1.6 s | CALIBRATED |
| Face-region motion floor | 10th percentile > 0.15 | CALIBRATED, 25 clips @ 24 fps 720p |
| Lip-sync lag | −0.045 s to +0.125 s, when correlation ≥ 0.3 | ITU-R BT.1359 detectability |
| Transcript word-hit | ≥ 70 % of scripted words | CALIBRATED |
| Mean volume | > −40 dB | CALIBRATED |
| Frames, by eye, every second, in order | the per-frame list and the temporal list below | CONSTRAINT (the procedure), judgment (the verdict) |
The whole-frame motion median does not work for dialogue [CALIBRATED]. Calibrated on moving scenes it reads above 1.0, but a locked-off talking head sits at 0.3–0.9 while performing normally. Gating on it condemns good work.
No metric can tell good motion from bad. A hallucinated object is motion, so it raises every score; the highest-scoring take of five was the broken one. The eye stays in the loop.
The temporal pass — every gate above is blind to it [CONSTRAINT]
Every metric in that table, and every item on the per-frame list, judges one frame at a time. A clip whose frames are each individually perfect can still be wrong across TIME, and that class of defect passes everything above while raising the motion score.
python clip_qa.py --strip <clips_dir> # 1 fps contact sheet, cell k = second k
A directory run writes the strips anyway, on purpose — this is the one gate whose input must not depend on anyone remembering to produce it. Read the strip in order and answer all seven; a defect is cited as a second, not as "looks off":
| # | Temporal failure | What it looks like on the strip |
|---|---|---|
| 1 | object scale drift | something in frame grows or shrinks across cells while the camera is still |
| 2 | materialisation / dissolve | an object or a fragment of one is absent in early cells and present later, or the reverse |
| 3 | identity swap | a face that is one person early and another later |
| 4 | wardrobe change | a garment, colour or prop that changes between cells |
| 5 | background morph | terrain, horizon or architecture that rearranges behind held actors |
| 6 | extra limb or person | a count that changes between cells |
| 7 | axis break | a subject that crosses to the wrong side of frame mid-shot |
One frame is not the pass, and neither is a four-frame filmstrip [CALIBRATED, one clip]. On 2026-09-07 a beat's background monolith started as a distant stub, had a detached fragment appear at frame-top around 2.4 s, then grew to several times its size and loomed behind the actors. It passed the letterbox check, both stream-length checks, the audio check and every motion gate. It was accepted twice: once off a single frame at ~3.3 s, by which point the object was already large and stable; and again off a four-frame filmstrip on the review page, where the artifact is plainly visible and was read past. The account owner caught it by watching the clip.
The cause was the prompt, and it is a repeatable trap. The beat asked for "the first sunlight strikes the top of the monolith and travels slowly down its face" together with "very slow rise" on the camera. A lighting instruction phrased as downward travel, plus a rising camera, reads as licence to build the object top-down and change its scale. Describe a light state, not a light journey, and state explicitly that the object holds its size and position — the re-shoot that fixed it says "already fully visible from the first frame, holding exactly the same size, shape and position for the whole shot" and "the camera fixed and completely still".
Failure → delete the clip, change one thing, re-check. A second identical failure means the diagnosis is wrong: restage or delete the beat rather than rewrite the prompt again.
Step 9 — assemble and hand over
Lane A joins with scene create and per-clip trims, free and server-side. Otherwise ffmpeg, and join with the concat filter, not the demuxer — mixed frame rates through the demuxer produced 164 s of video under 171 s of audio, lips running 4 % ahead [CALIBRATED]. Title cards need one drawtext per line; a newline inside one renders literally as "nn". Captions come from the script, not the transcript, so the reader sees the correct line even where the engine fluffed it.
Ship a review page beside the cut: the final video, and every clip with its prompt, lines, transcript, metrics and frames.
Red flags — stop and re-plan
- Planning entities or plates before anyone looked at the final host URL.
- An age word anywhere near a person.
- A sign, poster, door or garment described as carrying words.
- A film format in the style block.
- Two
--reference-entityflags, orcharacters = [A, B]on one manifest scene. --durationwith no--model;--refwithveo-quality(it takes 0 — reach foromni-1.2).- A beat over 2.5 words per second, or a line shortened "to fit".
- Angles of one location generated as independent
t2icalls. - "Launch the rest in the background and check later."
- Accepting any clip without running a gate.
| Rationalisation | Reality |
|---|---|
| "Both faces must stay consistent, so both entities go in" | the second entity is the 400. One entity plus a role noun beats a refused generation. |
| "The room is described in every prompt, that is enough" | without an anchored plate chain, the first new angle invents a different room. |
| "Trim the speech so it fits 8 s" | split it across beats. The words are the deliverable. |
| "Reverse-angle drift is unavoidable" | it is avoidable: chain the angle off the anchor plate with i2i. |
| "Kick the batch off and review in the morning" | one template bug bills once per clip. Trial, gate, then pairs. |
| "It looks fine" | run the gates. Two clips that looked fine carried audible lag. |
What this skill does not cover
Untested here, not discouraged. If you try one and it works, add a scored task and say so in optimization_notes.
[UNEXPLORED] seed locking across generations for consistency · a single-image storyboard sheet fed to a video model as a generation input rather than a review artefact · first-and-last-frame interpolation for transitions · custom voices and voice references · agent-mode brief cards · character archetype generation · manifest runs at large scale · reference-to-video at high reference counts · non-English delivery, which Google documents as unevaluated · and on the tooling side, a real face detector in place of clip_qa.py's fixed crop, plus frame-rate normalisation in the motion metric.
Keeping this skill honest
The repo ships a scored harness. Measure before and after any edit:
python scripts/dev/skillopt/harness.py --skill skills/video-production/SKILL.md \
--tasks skills/video-production/tasks.json --dry-run
tasks.json beside this file holds the scored scenarios; every entry exists because an agent got it wrong in a rollout. When you find a new failure, add a task first, confirm it fails, then edit the skill until it passes. A rule added without a failing task is a guess.
Reference
consistency.md— character sheets, environment sets, prop sheets, film grammarcomposition.md— reference budget and ordering, command chains per production shapefailure-modes.md— symptom to cause to fixclip_qa.py— the gatestasks.json— the scored set
MCP servers 1
Sponsors
Details
- Marketplace
- ffroliva/gflow-cli
- Source
- plugins/gflow
- Category
- Developer Tools