Nano Image Generator

#!/usr/bin/env python3
"""
Nano Image Generator - Generate images using Google's Gemini 3 Pro Preview API.

Requires: Set your GEMINI_API_KEY in the get_api_key() function below.

Usage:
    python generate_image.py "A cute robot mascot" --output ./mascot.png
    python generate_image.py "Banner for app launch" --aspect 16:9 --output ./banner.png
    python generate_image.py "High-res logo" --size 4K --output ./logo.png

    # With reference images (style transfer, character consistency):
    python generate_image.py "Same character in a forest" --ref ./character.png --output ./forest.png
    python generate_image.py "Transform to watercolor style" --ref ./photo.jpg --output ./watercolor.png
    python generate_image.py "Combine these two" --ref ./img1.png --ref ./img2.png --output ./combined.png
"""

import argparse
import base64
import json
import os
import sys
import urllib.request
import urllib.error
from pathlib import Path


# Gemini 3 Pro Preview - the "Nano Banana Pro" model
MODEL_ID = "gemini-3-pro-image-preview"

ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
IMAGE_SIZES = ["1K", "2K", "4K"]

API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"


def get_api_key():
    """
    Get API key.

    ⚠️ SETUP REQUIRED: Replace the placeholder below with your Gemini API key.

    Get your API key from: https://aistudio.google.com/apikey
    """
    return "YOUR_GEMINI_API_KEY_HERE"  # <-- Replace this with your API key


def detect_image_format(image_bytes: bytes) -> tuple[str, str]:
    """
    Detect actual image format from magic bytes.
    Returns: (mime_type, extension)

    Gemini API sometimes reports incorrect mime types, so we verify
    the actual format from the image data itself.
    """
    if image_bytes[:8] == b'\x89PNG\r\n\x1a\n':
        return "image/png", ".png"
    elif image_bytes[:2] == b'\xff\xd8':
        return "image/jpeg", ".jpg"
    elif image_bytes[:4] == b'RIFF' and image_bytes[8:12] == b'WEBP':
        return "image/webp", ".webp"
    elif image_bytes[:6] in (b'GIF87a', b'GIF89a'):
        return "image/gif", ".gif"
    else:
        # Default to PNG if unknown
        return "image/png", ".png"


def load_image_as_base64(image_path: str) -> tuple[str, str]:
    """
    Load an image file and return (base64_data, mime_type).
    """
    path = Path(image_path)
    if not path.exists():
        print(f"Error: Reference image not found: {image_path}", file=sys.stderr)
        sys.exit(1)

    image_bytes = path.read_bytes()
    mime_type, _ = detect_image_format(image_bytes)
    base64_data = base64.b64encode(image_bytes).decode("utf-8")
    return base64_data, mime_type


def generate_image(
    prompt: str,
    aspect_ratio: str = "1:1",
    image_size: str = "2K",
    reference_images: list[str] | None = None,
) -> tuple[bytes, str]:
    """
    Generate an image using Gemini 3 Pro Preview API.

    Args:
        prompt: Text description for the image
        aspect_ratio: Output aspect ratio
        image_size: Output resolution (1K, 2K, 4K)
        reference_images: List of paths to reference images (up to 14)

    Returns: (image_bytes, mime_type)
    """
    api_key = get_api_key()

    if api_key == "YOUR_GEMINI_API_KEY_HERE":
        print("Error: Please set your API key in scripts/generate_image.py", file=sys.stderr)
        print("Edit the get_api_key() function and replace YOUR_GEMINI_API_KEY_HERE", file=sys.stderr)
        sys.exit(1)

    url = f"{API_BASE}/{MODEL_ID}:generateContent?key={api_key}"

    # Build parts list - text prompt first, then reference images
    parts = [{"text": prompt}]

    # Add reference images if provided
    if reference_images:
        if len(reference_images) > 14:
            print("Warning: Maximum 14 reference images supported, using first 14", file=sys.stderr)
            reference_images = reference_images[:14]

        for img_path in reference_images:
            base64_data, mime_type = load_image_as_base64(img_path)
            parts.append({
                "inlineData": {
                    "mimeType": mime_type,
                    "data": base64_data
                }
            })
            print(f"Added reference image: {img_path}", file=sys.stderr)

    # Build request payload per Gemini 3 Pro Preview spec
    payload = {
        "contents": [{"parts": parts}],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {
                "aspectRatio": aspect_ratio,
                "imageSize": image_size,
            },
        },
    }

    # Make request
    headers = {"Content-Type": "application/json"}
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(url, data=data, headers=headers, method="POST")

    try:
        with urllib.request.urlopen(req, timeout=180) as response:
            result = json.loads(response.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        error_body = e.read().decode("utf-8")
        print(f"API Error ({e.code}): {error_body}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"Network Error: {e.reason}", file=sys.stderr)
        sys.exit(1)

    # Extract image from response
    candidates = result.get("candidates", [])
    if not candidates:
        print("Error: No candidates in response", file=sys.stderr)
        print(f"Response: {json.dumps(result, indent=2)}", file=sys.stderr)
        sys.exit(1)

    parts = candidates[0].get("content", {}).get("parts", [])

    for part in parts:
        if "inlineData" in part:
            inline_data = part["inlineData"]
            image_bytes = base64.b64decode(inline_data["data"])
            # Detect actual format from magic bytes (API mime_type can be wrong)
            actual_mime, _ = detect_image_format(image_bytes)
            reported_mime = inline_data.get("mimeType", "image/png")
            if actual_mime != reported_mime:
                print(f"Note: API reported {reported_mime}, actual format is {actual_mime}", file=sys.stderr)
            return image_bytes, actual_mime

    # No image found - check for text response
    for part in parts:
        if "text" in part:
            print(f"Model response (no image): {part['text']}", file=sys.stderr)

    print("Error: No image data in response", file=sys.stderr)
    sys.exit(1)


def get_extension(mime_type: str) -> str:
    """Get file extension from MIME type."""
    extensions = {
        "image/png": ".png",
        "image/jpeg": ".jpg",
        "image/webp": ".webp",
        "image/gif": ".gif",
    }
    return extensions.get(mime_type, ".png")


def main():
    parser = argparse.ArgumentParser(
        description="Generate images using Gemini 3 Pro Preview (Nano Banana Pro)",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s "A friendly robot mascot" --output ./robot.png
  %(prog)s "Website banner" --aspect 16:9 --output ./banner.png
  %(prog)s "Detailed landscape" --size 4K --output ./landscape.png

  # With reference images (style transfer, character consistency):
  %(prog)s "Same character in a forest" --ref ./char.png -o ./forest.png
  %(prog)s "Transform to watercolor" --ref ./photo.jpg -o ./watercolor.png
  %(prog)s "Combine styles" --ref ./img1.png --ref ./img2.png -o ./combined.png
        """,
    )
    parser.add_argument("prompt", help="Image description/prompt")
    parser.add_argument(
        "--output", "-o",
        required=True,
        help="Output file path (extension auto-added if missing)",
    )
    parser.add_argument(
        "--aspect", "-a",
        choices=ASPECT_RATIOS,
        default="1:1",
        help="Aspect ratio. Default: 1:1",
    )
    parser.add_argument(
        "--size", "-s",
        choices=IMAGE_SIZES,
        default="2K",
        help="Image resolution: 1K, 2K, or 4K. Default: 2K",
    )
    parser.add_argument(
        "--ref", "-r",
        action="append",
        dest="reference_images",
        metavar="IMAGE",
        help="Reference image for style transfer or character consistency (can use multiple times, max 14)",
    )

    args = parser.parse_args()

    print(f"Generating image with Gemini 3 Pro Preview...", file=sys.stderr)
    print(f"Prompt: {args.prompt}", file=sys.stderr)
    print(f"Aspect: {args.aspect}, Size: {args.size}", file=sys.stderr)
    if args.reference_images:
        print(f"Reference images: {len(args.reference_images)}", file=sys.stderr)

    image_bytes, mime_type = generate_image(
        prompt=args.prompt,
        aspect_ratio=args.aspect,
        image_size=args.size,
        reference_images=args.reference_images,
    )

    # Determine output path - always use correct extension for actual format
    output_path = Path(args.output)
    correct_ext = get_extension(mime_type)

    # Replace any user-specified extension with the correct one
    output_path = output_path.with_suffix(correct_ext)

    if args.output != str(output_path):
        print(f"Note: Using {correct_ext} extension (actual format: {mime_type})", file=sys.stderr)

    # Create parent directories if needed
    output_path.parent.mkdir(parents=True, exist_ok=True)

    # Write image
    output_path.write_bytes(image_bytes)

    print(f"Image saved: {output_path}", file=sys.stderr)
    # Print path to stdout for easy capture
    print(output_path)


if __name__ == "__main__":
    main()

{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-01-17T08:18:14.485Z",
    "slug": "lxfater-nano-image-generator",
    "source_url": "https://github.com/lxfater/nano-image-generator-skill/tree/main/",
    "source_ref": "main",
    "model": "claude",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "d950ddcfecf634438c709d63029b08c98d9c92106bf970542ab5280b139ba1ab",
    "tree_hash": "46abc6fe60cbed24eb09ea4d60a40bda3a2336958318000d12664d80463c41a9"
  },
  "skill": {
    "name": "nano-image-generator",
    "description": "Generate images using Nano Banana Pro (Gemini 3 Pro Preview). Use when creating app icons, logos, UI graphics, marketing banners, social media images, illustrations, diagrams, or any visual assets. Supports reference images for style transfer and character consistency. Triggers include phrases like 'generate an image', 'create a graphic', 'make an icon', 'design a logo', 'create a banner', 'same style as', 'keep the style', or any request needing visual content.",
    "summary": "Generate images using Nano Banana Pro (Gemini 3 Pro Preview). Use when creating app icons, logos, UI...",
    "icon": "🖼️",
    "version": "1.0.0",
    "author": "lxfater",
    "license": "MIT",
    "category": "design",
    "tags": [
      "image-generation",
      "gemini",
      "ai-art",
      "design",
      "graphics"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "network",
      "filesystem",
      "env_access"
    ]
  },
  "security_audit": {
    "risk_level": "safe",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "This skill is a legitimate image generation tool using Google's Gemini API. The static analyzer flagged 217 issues, but nearly all are false positives from documentation files containing code examples in markdown. The actual executable code (generate_image.py) contains only legitimate API calls to Google's Gemini service with no malicious behavior.",
    "risk_factor_evidence": [
      {
        "factor": "network",
        "evidence": [
          {
            "file": "scripts/generate_image.py",
            "line_start": 23,
            "line_end": 24
          },
          {
            "file": "scripts/generate_image.py",
            "line_start": 34,
            "line_end": 34
          },
          {
            "file": "scripts/generate_image.py",
            "line_start": 144,
            "line_end": 147
          }
        ]
      },
      {
        "factor": "filesystem",
        "evidence": [
          {
            "file": "scripts/generate_image.py",
            "line_start": 73,
            "line_end": 78
          },
          {
            "file": "scripts/generate_image.py",
            "line_start": 265,
            "line_end": 268
          }
        ]
      },
      {
        "factor": "env_access",
        "evidence": [
          {
            "file": "scripts/generate_image.py",
            "line_start": 37,
            "line_end": 45
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 5,
    "total_lines": 922,
    "audit_model": "claude",
    "audited_at": "2026-01-17T08:18:14.485Z"
  },
  "content": {
    "user_title": "Generate images using Gemini 3 Pro with style references",
    "value_statement": "Creating visual assets for projects often requires expensive design tools or manual illustration. This skill enables instant image generation using Google Gemini 3 Pro Preview API with support for reference images to maintain consistent style and character appearance across multiple assets.",
    "seo_keywords": [
      "Claude",
      "Claude Code",
      "image generation",
      "Gemini API",
      "AI art",
      "design automation",
      "style transfer",
      "visual assets",
      "graphic design",
      "app icons"
    ],
    "actual_capabilities": [
      "Generate images from text descriptions using Gemini 3 Pro Preview API",
      "Support up to 14 reference images for style transfer and character consistency",
      "Output images in multiple aspect ratios including square, portrait, landscape, and cinematic formats",
      "Create images at 1K, 2K, or 4K resolution",
      "Automatically detect and save images in correct format including PNG, JPEG, WebP, and GIF",
      "Process style references to maintain visual consistency across image series"
    ],
    "limitations": [
      "Requires manual API key configuration by editing Python source code",
      "Maximum 14 reference images per generation request",
      "Text rendering within generated images may be imperfect",
      "Specific brand logos may not reproduce exactly due to API limitations"
    ],
    "use_cases": [
      {
        "target_user": "Mobile app developers",
        "title": "Create app icons and launch graphics",
        "description": "Generate app icons, splash screens, and promotional graphics in appropriate aspect ratios for iOS and Android stores."
      },
      {
        "target_user": "Content creators",
        "title": "Design social media visual assets",
        "description": "Create consistent visual content for platforms with specific format requirements like Instagram posts and YouTube thumbnails."
      },
      {
        "target_user": "Web developers",
        "title": "Generate website hero images and banners",
        "description": "Produce high-resolution hero banners, background images, and UI graphics matching brand guidelines using reference images."
      }
    ],
    "prompt_templates": [
      {
        "title": "Basic image generation",
        "scenario": "Create a simple graphic",
        "prompt": "Generate an image of a friendly robot mascot waving, flat design style, purple gradient background"
      },
      {
        "title": "Specific aspect ratio",
        "scenario": "Social media content",
        "prompt": "Create a website hero banner for a productivity app with abstract geometric shapes in blue and white, 16:9 aspect ratio"
      },
      {
        "title": "Style transfer",
        "scenario": "Match existing design",
        "prompt": "Generate a new character illustration in the same visual style as the reference image, keeping the color palette and artistic approach"
      },
      {
        "title": "Character consistency",
        "scenario": "Series of related images",
        "prompt": "Show the same character from the reference image in a forest setting with warm lighting, maintaining character appearance and proportions"
      }
    ],
    "output_examples": [
      {
        "input": "Generate an app icon for a weather app, minimalist cloud and sun design, blue gradient",
        "output": [
          "Image saved to specified output path",
          "Square 1:1 aspect ratio suitable for app stores",
          "PNG format with transparent or gradient background",
          "Resolution matches requested size (1K, 2K, or 4K)"
        ]
      },
      {
        "input": "Create a marketing banner with the same style as my brand image, 21:9 cinematic ratio",
        "output": [
          "Wide cinematic banner matching reference image style",
          "Visual elements inherit color palette from reference",
          "High-resolution output suitable for web headers",
          "Consistent brand aesthetic maintained across assets"
        ]
      }
    ],
    "best_practices": [
      "Include specific style descriptors in prompts such as flat design, photorealistic, watercolor, or minimalist to guide output",
      "Use reference images when generating multiple related assets to maintain visual consistency across a project or campaign",
      "Specify aspect ratios that match your target platform requirements such as 1:1 for app icons or 16:9 for web banners"
    ],
    "anti_patterns": [
      "Avoid requesting complex text rendering within images as AI generation handles text poorly; overlay text separately instead",
      "Do not expect exact reproduction of specific brand logos or copyrighted characters; use for inspiration and original designs",
      "Avoid using more than 14 reference images as the API will truncate the list and ignore additional references"
    ],
    "faq": [
      {
        "question": "How do I configure my Gemini API key?",
        "answer": "Edit scripts/generate_image.py and replace YOUR_GEMINI_API_KEY_HERE in the get_api_key function with your actual key from aistudio.google.com/apikey"
      },
      {
        "question": "What image formats are supported for output?",
        "answer": "The skill automatically detects and saves images in PNG, JPEG, WebP, or GIF format based on what the Gemini API returns"
      },
      {
        "question": "Can I use this to maintain character consistency across multiple images?",
        "answer": "Yes, generate your first character image then use it as a reference image with --ref flag for subsequent generations to maintain appearance"
      },
      {
        "question": "What aspect ratios are available?",
        "answer": "Supports 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, and 21:9 aspect ratios for various use cases from icons to cinematic banners"
      },
      {
        "question": "How do reference images work for style transfer?",
        "answer": "Add reference images using --ref flag; the model analyzes visual style, colors, and artistic approach to apply similar aesthetics to new generations"
      },
      {
        "question": "Is there a cost to using this skill?",
        "answer": "The skill itself is free, but you need a Gemini API key which may have usage costs depending on Google's pricing for the API"
      }
    ]
  },
  "file_structure": [
    {
      "name": "scripts",
      "type": "dir",
      "path": "scripts",
      "children": [
        {
          "name": "generate_image.py",
          "type": "file",
          "path": "scripts/generate_image.py",
          "lines": 277
        }
      ]
    },
    {
      "name": "README_CN.md",
      "type": "file",
      "path": "README_CN.md",
      "lines": 131
    },
    {
      "name": "README.md",
      "type": "file",
      "path": "README.md",
      "lines": 131
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 146
    }
  ]
}