model — pass ONE of these exact ids (from GET v1/flow/models, verified 2026-07-25):
  BELUGA       = "Nano Banana 2"      — the DEFAULT, ~30s (legacy id NARWHAL is accepted as an alias)
  GEM_PIX_2    = "Nano Banana Pro"    — highest quality, ~40s, has a separate DAILY
                                        per-account quota (429 rotates accounts)
  HARBOR_SEAL  = "Nano Banana 2 Lite" — ~40s
Anything else is rejected with HTTP 400 — there is no silent fallback, so a wrong id
wastes a round trip, not credits. Do NOT guess names like "nano_banana_pro": that is
the model FAMILY key from the config, not the id the generate call takes.

image_inputs: mediaIds from prior generations, edit-in-place (keeps them pixel-exact).
control_images: up to 10 base64 image bytes (no data: prefix) of a locally rendered layout/control
image — uploaded first, then prepended to image_inputs so the generator follows an exact
spatial layout instead of prose. For whole-scene layout control prefer generate_scene.

seed: 1..900000, fixes the generation so the same request returns the same image. Omit
for a random seed. Needed to compare two prompts, two models or two control images
honestly — without it every run is a fresh roll and the difference you are measuring
drowns in noise. Measured 2026-08-09: with an UNCHANGED control image a fixed seed
reproduces the frame to ~0.1%; once the control image changes, the seed no longer keeps
the character — for that use image_inputs with a reference frame's mediaId.

project_id: put the result into a project made with create_project instead of the
account's default one — one project per end client keeps their work separate. Omit it
and nothing changes from before.

include_preview: ON by default since 2026-08-21 — a generated image nobody can see
in the chat is half a result. Pass False to get the plain dict back and nothing else
(worth doing in a loop of many generations, where the previews would fill the
context). When on and the job finished with at least one url, the call returns the
usual result dict, a short card naming the parameters actually used, and a small
compressed JPEG (long side capped at 768px, ~100-160KB once base64-encoded) as an
inline image content block, so a human can actually see the result without leaving
the chat. This is deliberately a shrunk preview, never the original — the real Flow
image is ~0.5MB (~740KB in base64), enough to burn a whole tool call's worth of a
client's context budget on its own. The preview is for EYES ONLY: urls/media_ids
stay the authoritative result in both modes, and every downstream call (upscale_image,
image_inputs edit-in-place, ...) must keep using media_ids, never the preview bytes.
If the preview download/shrink fails for any reason, this silently falls back to the
plain (no-preview) result instead of failing the whole call.

SAVE THE RESULT INTO THE USER'S PROJECT. A finished job also carries `download_urls`
(plain URLs, no auth header needed) and `save_as` (the filenames to use). Unless the
user said otherwise, write them to ./media/<save_as> in their working directory and
tell them the path. The server keeps its own copy, but only the file in their project
is theirs: our copy can be reclaimed when the disk fills, and the URLs expire within
the hour. Downloading costs no credits and no quota.

Returns {"urls": [...], "media_ids": [...]} when done, or a job_id to poll
with check_job if it's not ready within ~60s (rare for images unless the
device is cold). With the default include_preview=True and a finished result,
returns [that dict, <card>, <inline image>] instead — see include_preview above.
idempotency_key: optional, any string unique to this logical request (e.g. a uuid).
  Repeating a call with the same key within 24h returns the SAME job instead of a
  new one — use it when you may retry after a timeout or a busy error.