gemini_interact
Generate and refine images with Gemini's Interactions API. Chain multi-turn edits by passing the previous interaction ID to maintain context for step-by-step modifications.
Instructions
Preferred tool for iterative or multi-step refinement of a single image — multi-turn generation/editing via Gemini's Interactions API. To refine, capture the returned interaction id and pass it as previous_interaction_id on the next call — do NOT start a new interaction or re-upload the image for each tweak. continue_last: true chains from this session's most recent interaction without threading the id. If a call times out on the client side, the generation usually still completes: the image plus a <image>.json sidecar recording its interaction id land in the output dir, and continue_last: true still resumes that interaction — check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as chain_recovered (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). Output is JPEG.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| async | No | Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off. | |
| input | Yes | Text prompt or editing instruction | |
| model | No | Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding). | |
| images | No | Paths to reference input images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. | |
| inline | No | Return base64 images inline instead of writing to disk | |
| confirm | No | Must be true to proceed. Without this, the tool returns a preview. | |
| filename | No | Base filename for the output image (extension stripped; default: slugified input) | |
| video_url | No | Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image) | |
| image_size | No | Output resolution (512 = 0.5K, Flash-only) | |
| images_url | No | Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*). | |
| output_dir | No | Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd) | |
| timeout_ms | No | Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s) | |
| video_path | No | Path to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url. | |
| max_wait_ms | No | Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: "running" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set. | |
| orientation | No | Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given. | |
| aspect_ratio | No | Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given. | |
| search_types | No | Grounding search types (implies google_search). image_search (gemini-3.1-flash-image only) uses Google Image Search results as visual references; per Google ToS the returned grounding.search_suggestions HTML must then be displayed to the user. Cannot depict real people from web images. | |
| continue_last | No | Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir. | |
| google_search | No | Ground the image in live Google Search results (current events, weather, data) | |
| images_base64 | No | Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. | |
| from_clipboard | No | Use the image currently on the macOS system clipboard as an input (downscaled to JPEG) | |
| thinking_level | No | Reasoning depth; higher can help complex/structural edits | |
| idempotency_key | No | Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge. | |
| images_file_uris | No | Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving. | |
| previous_interaction_id | No | ID from a prior gemini_interact call — continues that multi-turn conversation |