Gemini Webapi

Gemini web-app toolkit

A local CLI wrapper around the unofficial gemini_webapi library (github.com/HanaokaYuzu/Gemini-API) that drives gemini.google.com via the user's Google cookies (not an official API key). Installed at:

C:\Users\user\Desktop\video-ad\tools\gemini\

Full docs: C:\Users\user\Desktop\video-ad\tools\gemini\README.md. Upstream source/examples: ...\tools\gemini\repo\ (README.md, cli.py, src/).

The venv python (always use this, never global python)

C:\Users\user\Desktop\video-ad\tools\gemini\venv\Scripts\python.exe

What it does

• ✅ text/documents/scripts/copy, ✅ AI images (Nano Banana), ✅ short video + avatar (Gemini Omni, paid plan), ✅ audio/music beds.

Image models ("Nano Banana")

Image gen runs on the chat model. --model gemini-3-pro → Nano Banana Pro (best, hero shots); --model gemini-3-flash → Nano Banana 2 (fast, default for image). The account default (3.1 Flash-Lite) has a tight image cap — the image/video commands already avoid it. Images carry a Gemini watermark.

Video + Avatar (Gemini Omni) — GENERATE, THEN PULL

• Account is on a PAID plan; default for avatar video is Gemini Omni.
• Avatar handle: @ai844579 — pass --avatar @ai844579 (or put it in the prompt).
• Each generation is ~10 seconds. Voiceover cap: ≤ ~22–24 words per 10s clip (≈140 wpm) — user's rule. Keep each clip's narration within that.
• ⚠️ The live video stream almost always aborts before returning the file (error 1155 / "stream suspended / no CID to recover"). This is NOT failure — the video still renders server-side and lands in Gemini history. Retrieve it with pull, do not keep re-generating (that just burns the daily video cap):
  • PY gemini.py video "..." --avatar @ai844579 → submit (may end in a stream error, fine)
  • PY gemini.py pull --match video -o <dir> → downloads finished videos from history
  • PY gemini.py list → see recent chats; pull --cid c_xxxx targets one.
  • The user can also generate videos in the Gemini APP directly, then just pull.
• Daily video cap exists even on paid plans ("come back tomorrow"). pull still works to download already-made videos.
• Longer ad (~22–24s): pull 2–3 clips and concat with tools\ffmpeg.exe.
• HeyGen MCP (talking avatar + real voiceover) remains a reliable alternative if Gemini's daily cap is hit or a specific avatar/lipsync is needed.

Editing AI video clips — ALWAYS edit, never blindly concat

AI clips (Gemini Omni etc.) have morphing/warping, weak first/last beats, garbled on-screen text/logos, and per-clip audio that clashes when joined. Act like a video editor with a timeline, not a concat script. Workflow (uses tools\ffmpeg.exe):

1. Look at every clip's frames DENSELY. 1 fps hides sub-second glitches — use 4 fps and split each 10s clip into readable windows so frames are big enough to actually see (per 5s window = 20 frames in a 5x4 grid): ffmpeg -i clip.mp4 -ss 0 -t 5 -vf "fps=4,scale=440:-1,tile=5x4" -frames:v 1 w0.png ffmpeg -i clip.mp4 -ss 5 -t 5 -vf "fps=4,scale=440:-1,tile=5x4" -frames:v 1 w5.png READ every window. Frames are 0.25s apart, left→right, top→bottom, so you can name the exact second an artifact starts. Watch for: morphing faces, warped/garbled on-screen TEXT or fake LOGOS (a real example: one clip rendered a bogus "Ucire to HFT" logo at 8.5–9.75s — cut before it), empty/wide/tiny shots, ugly first/last frames. It's normal to keep only 2–4s of a 10s clip. (drawtext timestamps need a fontfile on Windows — skip it, use frame position instead.)
2. Look at the audio too. Waveform + stats per clip: ffmpeg -i clip.mp4 -filter_complex "showwavespic=s=1000x140" -frames:v 1 wave.png ffmpeg -i clip.mp4 -af volumedetect -f null - and silencedetect=noise=-38dB:d=0.3. Flag silent stretches and dead-air. Video-good-but-audio-bad and vice versa are common.
3. Cut to the good parts (frame-accurate = re-encode each segment, don't -c copy at arbitrary times). 3b. SEQUENCE — this is half the edit, not an afterthought. Cutting out bad frames is only step one. Then lay ALL the clean pieces on the board and decide the ORDER like a creative director, because AI clips come out scattered. Ask: what is the end goal of this video, and of each shot? Then order for story, not for the order the clips happened to generate in:
   • Hook (first 1–2s) = your single most scroll-stopping shot — motion, a light-up "moment," or the most striking beauty frame. Never open on a slow/empty/dark hold just because it feels like an "intro." Get to something arresting immediately.
   • Hero right after the hook = the money beauty shot of the product.
   • Feature beats in the middle (display, charging, etc.).
   • Detail (macro/craft) as a texture beat.
   • Breath (one calm elegant shot) before the finish.
   • Close = a strong final hero/standing shot that leaves the product in mind. Drive the order from the AUDIO / voiceover / transcript when there is one (picture follows the words); with no VO, drive it from the visuals and the ad's goal. Then re-watch (re-mosaic the assembled cut) and re-order again if the flow is off — a reveal-structure (dark→ignite→hero) and a hook-first structure (ignite→hero→…) are both valid; pick the one that serves the goal, don't just keep generation order.
4. Unify the audio. Don't keep 5 disjoint per-clip beds. Drop them and lay ONE continuous bed under the whole edit, with afade in/out. If a clip's audio is "just a sound," replace/overlay a better track (generate via gemini.py media, or HeyGen search_audio_sounds / a music bed). Align audio hits to visual cuts.
5. Target length = the user's spec (default a tight ~22–24s ad; ~140 wpm VO ⇒ ≤22–24 words per 10s of picture).
6. QC the result: mosaic the final cut and confirm no artifacts slipped in.

A worked example lives at tools\gemini\out\videos\build_edit.sh (curated segment list + silent montage + unified faded bed + mux). Reuse/adapt its structure.

Parallelize with subagents (faster + more professional)

Don't do a multi-clip edit serially in one context. Fan the work out with the Agent tool (or a Workflow) so the slow parts run concurrently and each agent stays focused:

• Frame-analysis agents — one PER clip (fan out): each generates its clip's dense 4fps mosaics, reads them, and returns structured clean/bad sub-ranges + one-line notes (e.g. "logo artifact 8.5–9.75"). N clips → N agents at once.
• Audio-analysis agent: waveform + silencedetect + volumedetect per clip; flags dead air, and whether each clip's audio is musical or just ambient.
• Sequencing/director agent: takes all findings, decides the goal + hook, and returns the ordered segment list (the §3b decision). This is the creative brain.
• Salvage agents: for beats where the AUDIO/VO is good but the VISUAL is weak, don't drop the beat — see below.
• QC agent: re-mosaics the assembled cut and flags anything that slipped through. Then the main context just assembles the approved segment list with ffmpeg. Result: the per-clip inspection (the slow part) happens in parallel, and the edit is more consistent.

Salvage weak visuals (good audio, bad picture)

When you must keep a beat for timing/VO but its footage is ugly (morphy, empty, dull): blur/darken it and put graphics on top to carry it — a real editor's move:

• Blur / darken bg: -vf "gblur=sigma=20,eq=brightness=-0.1"
• Overlay kinetic TEXT / lower-third: drawtext (needs a fontfile on Windows, e.g. fontfile=C\:/Windows/Fonts/arialbd.ttf), or render a transparent PNG and overlay.
• Add an emoji / sticker / logo PNG with overlay=x:y (optionally animated via expressions).
• Then the good audio/VO plays over a clean graphic beat instead of bad footage. Use sparingly — blur-and-text is a patch for a weak second, not a substitute for real shots.

Voiceover audio (spoken)

The COOKIE web app (gemini.py) cannot do TTS — it only makes music + Omni-video native VO. For a standalone spoken voiceover FILE there are two routes:

1. Gemini 2.5 TTS via the official API — tts.py (needs a free API KEY, separate from cookies). Accent/style is set by the PROMPT, so a Nigerian accent works: PY tts.py "Meet Series 11..." --accent "Nigerian English" --voice Charon -o vo.wav PY tts.py --list (list TTS models + prebuilt voices) Key setup (once): free key at https://aistudio.google.com/apikey → tools\gemini\gemini_api_key.txt (git-ignored) or env GEMINI_API_KEY. These 2.5 TTS models are API-only; they never appear in the web app's model list.
2. HeyGen MCP: create_speech (needs a starfish-engine voice — designed voices aren't starfish, so pick a starfish voice or clone_voice the user's own voice for a true Nigerian accent), or the avatar @ai844579's own voice via an Omni video.

Write the script first with doc (≤~22–24 words per 10s of picture), then TTS it.

Quick usage

Run from tools\gemini. PY = the venv python above.

Model choice: --model gemini-3-pro | gemini-3-flash | gemini-3-flash-thinking (default = account default). Images: the CLI auto-prepends "Generate" so you get AI images, not web images.

Auth (do first / when it breaks)

1. Preferred: tools\gemini\cookies.json with __Secure-1PSID (+ optional __Secure-1PSIDTS) copied from gemini.google.com DevTools → Cookies.
2. Or, if logged into gemini.google.com in the browser and no cookies.json, the [browser] extra auto-imports cookies.

• Never read, extract, print, or paste the user's cookies yourself. If auth fails (status 1016 UNAUTHENTICATED), tell the user to refresh cookies.json per README.md §2. Cookies expire regularly.

For anything beyond the CLI (chat sessions, gems, deep research)

Write a short async script against the venv using gemini_webapi.GeminiClient. The pattern and full API are in README.md §4 and repo\README.md.

Ad-workflow recipe (typical)

1. doc → generate the ad script + voiceover script (markdown).
2. image → generate hero shots / storyboard frames into the project's folder.
3. HeyGen create_speech → turn the VO script into spoken audio.
4. (optional) media → music bed; video → motion clips.
5. Assemble with tools\ffmpeg.exe (see project memories / existing workflow).