Nano Banana Pro Image Generation & Editing

intent

Generate new images or edit existing ones using Google's Nano Banana Pro API (Gemini 3 Pro Image). Use this skill when the user asks for image creation ("draw me a...", "generate an image of...") or image modification ("make the sky darker", "change this to watercolor"). Supports both text-to-image and image-to-image workflows with three resolution tiers (1K, 2K, 4K). The default workflow starts at 1K for fast iteration, then scales to 4K once the prompt is locked.

inputs

Required:

• --prompt: Text description (generation) or editing instructions (image-to-image). String, no length limit enforced by skill but keep under 500 chars for best results.
• --filename: Output PNG filename. Format: yyyy-mm-dd-hh-mm-ss-descriptive-name.png. String.

Optional:

• --input-image: Path to an existing image for editing. String (absolute or relative path). Skip for generation-only requests.
• --resolution: One of 1K, 2K, or 4K (uppercase). Defaults to 1K if omitted.
• --api-key: Gemini API key. String. Override environment variable if provided.

External Connections:

• Google Gemini 3 Pro Image API: Requires valid API key. Set via GEMINI_API_KEY environment variable or pass --api-key flag. OAuth scope: generative-ai-platform.googleapis.com. No rate limits documented publicly; expect standard Google Cloud quotas (typically 60 req/min for free tier, higher for paid).

Environment:

• GEMINI_API_KEY: Must be set or passed as --api-key. If neither exists, skill exits with error.
• uv: UV Python runner must be installed and in PATH.

Context:

• Current working directory: Script saves output images here by default (not in skill directory). User must have write permissions.

procedure

1. Validate prerequisites (input: user request, environment):

   • Check command -v uv exists in PATH.
   • Check GEMINI_API_KEY env var OR --api-key argument is provided. If neither, exit with "Error: No API key provided."
   • If --input-image is specified, verify file exists and is readable. If not, exit with "Error loading input image: [path]".
   • Output: Go/no-go signal.

2. Parse or infer resolution (input: user request, --resolution flag):

   • If user specifies no resolution, default to 1K.
   • If user says "low resolution", "1080", "1080p", or "1K", use 1K.
   • If user says "2K", "2048", "normal", or "medium resolution", use 2K.
   • If user says "high resolution", "high-res", "hi-res", "4K", or "ultra", use 4K.
   • If --resolution flag provided, use that value (case-insensitive, normalize to uppercase).
   • Output: resolved resolution parameter (1K, 2K, or 4K).

3. Generate or infer filename (input: user request, --filename flag):

   • If --filename provided, use it as-is.
   • If not provided, generate: yyyy-mm-dd-hh-mm-ss-{descriptive-name}.png.
     • Timestamp: current date/time in 24-hour format.
     • Descriptive name: 1-5 lowercase words from user's prompt or context, joined by hyphens. If unclear, use random identifier (e.g., x9k2).
   • Output: full filename string.

4. Prepare prompt (input: user request, --input-image flag):

   • For generation (no --input-image): pass user's image description as-is to --prompt. Only rework if clearly insufficient or incoherent.
   • For editing (--input-image provided): expect editing instructions in --prompt (e.g., "make the sky more dramatic", "remove the person", "change to cartoon style"). Optionally expand using the editing template: "Change ONLY: [single change]. Keep identical: subject, composition/crop, pose, lighting, color palette, background, text, and overall style. Do not add new objects."
   • Output: finalized prompt string.

5. Execute API call (input: prompt, filename, resolution, input-image path, API key):

   • Run: uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "{prompt}" --filename "{filename}" --resolution {resolution} [--input-image "{input-image}"] [--api-key "{api-key}"]
   • Send request to Google Gemini 3 Pro Image API endpoint.
   • Output: PNG file written to current working directory (or specified subdirectory in filename path).

6. Handle API response (input: API response, network conditions):

   • On success: script outputs full path to generated PNG file.
   • On network timeout (>30 sec): retry once. If retry fails, return error message with timeout details.
   • On rate limit (429 HTTP): wait 60 seconds, then retry once. If still rate-limited, inform user quota is exhausted.
   • On authentication error (401/403): return "Invalid API key or insufficient permissions. Check GEMINI_API_KEY."
   • On invalid input (empty prompt, unsupported file format): return specific error message (e.g., "Error: --prompt cannot be empty").
   • Output: success path, or error code/message.

7. Confirm to user (input: success/failure from step 6):

   • If success: inform user of saved file path. Do not read the image back or display it.
   • If failure: show error message and suggest fix (e.g., "Invalid API key", "Image path not found", "API quota exceeded").
   • Output: user-facing confirmation or error message.

decision points

Resolution fallback:

• If user specifies resolution but value is invalid (not 1K/2K/4K), default to 1K and log a warning.

API key source:

• If --api-key argument is provided, use it (highest priority).
• Else if GEMINI_API_KEY environment variable is set, use it.
• Else exit with "Error: No API key provided."

Image editing vs. generation:

• If --input-image path is provided and file exists, treat request as image editing. Prompt should contain editing instructions.
• If --input-image is not provided or file does not exist, treat request as text-to-image generation. Prompt should contain image description.
• If --input-image is provided but file does not exist, fail fast with "Error loading input image: [path]".

Filename handling:

• If user provides --filename with directory path (e.g., subdir/image.png), create subdirectory if it does not exist and save there.
• If user provides filename without directory, save to current working directory.
• If filename already exists, overwrite silently (user can manage versioning via timestamp or different names).

Prompt clarity:

• If user's prompt is vague or unclear, optionally expand using provided templates (generation or editing). Do not expand if user's intent is already clear.
• For editing, always preserve user's creative intent. Use template only to clarify which elements to keep/change.

Rate limit / quota:

• On 429 (rate limit): wait 60 sec, retry once. If still 429, inform user and do not retry again.
• On 403 (quota exceeded or no API access): do not retry. Inform user to check Google Cloud project quota or API enablement.

Network timeout:

• If API request hangs >30 sec, cancel and retry once. If second attempt also times out, return error.

Empty result set:

• If API returns success but image file is empty or corrupted, return "Error: API returned empty response. Try again or check API status."

output contract

Success case:

• A PNG file saved to the user's current working directory (or specified path in filename).
• Filename format: yyyy-mm-dd-hh-mm-ss-descriptive-name.png (if auto-generated) or user-provided filename.
• File size: typically 500 KB to 5 MB depending on resolution (1K smaller, 4K larger).
• Script outputs the full absolute path to the saved PNG (e.g., /Users/alice/projects/2025-11-23-14-23-05-japanese-garden.png).

Failure case:

• No file created.
• Script outputs error message (e.g., "Error: No API key provided", "Error loading input image: [path]", "API returned 403: Quota exceeded").
• Error message includes actionable fix when possible.

outcome signal

• User receives the full path to the generated/edited PNG file and can immediately open it in their image viewer.
• If iterating (draft → iterate → final), user sees new PNG file for each run with a new timestamp in the filename.
• If editing, user confirms that the edit was applied correctly by opening the output image.
• If skill fails, user sees a clear error message and knows the next step (check API key, verify image path, wait for rate limit reset, etc.).