/sketch

API Integration Reference

Purpose: Read this when Sketch needs canonical Gemini API integration rules, compatibility notes, error handling, rate guidance, or SynthID handling details.

Contents

• SDK compatibility
• Authentication
• Request patterns
• Parameter rules
• Response handling
• Error handling
• Rate and cost guidance
• SynthID documentation

SDK Compatibility

Verified baseline:

• google-genai SDK v1.38.0
• Google AI API with API-key auth
• default model: gemini-3.1-flash-image

Default guidance:

• keep docs and code v1.38+ compatible unless the user explicitly targets v1.50+

Authentication

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

Setup guidance:

pip install google-genai
export GEMINI_API_KEY="your-api-key-here"

Always include:

# .env
GEMINI_API_KEY=your-api-key-here

# .gitignore
.env
*.env
.env.*

Model Rules

Rules:

• default to gemini-3.1-flash-image; use gemini-3-pro-image for the most demanding professional workflows
• gemini-2.5-flash-image is a legacy option, not the default
• Imagen 4 endpoints were shut down on 2026-08-17; migrate to Gemini 3 image models

Request Patterns

Text-to-image

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents="A modern minimalist workspace, soft natural lighting, widescreen 16:9 composition",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
    ),
)

Text + image response

Use response_modalities=["TEXT", "IMAGE"] when the text explanation matters.

Reference-based editing

Pass the reference image with types.Part.from_bytes(...) (Base64 inlineData) plus the edit instruction.

Important: Do not use the Files API (fileData) for reference/source images in editing workflows — it causes silent failures where the model returns text instead of an edited image. Always use inlineData (Base64-encoded).

Iterative editing

Use client.chats.create(...) for multi-turn image refinement.

With Nano Banana 2, the model uses Thought Signatures to preserve visual context between conversation turns. This means you do not need to re-send the full image each turn — the model retains the visual state. Only re-send the base image if you are changing it entirely.

Grounding with Google Image Search

Available for Nano Banana 2 (gemini-3.1-flash-image). Enable via google_search tool config to allow the model to reference real-world images during generation, improving accuracy for specific objects, styles, or scenes.

Style transfer

Pass multiple reference images plus the transformation instruction.

Parameter Rules

response_modalities

Prompt-based controls for v1.38+

Aspect ratio guide

Reference-image limits

• maximum 14 reference images per request
• supported formats: PNG, JPEG, WebP, GIF first frame
• recommended maximum size: 4MB per reference image

Response Handling

Always:

• save images with timestamped filenames
• capture text responses when TEXT is requested
• write metadata.json

Suggested metadata fields:

{
  "generated_at": "...",
  "prompt": "...",
  "model": "gemini-3.1-flash-image",
  "files": ["..."],
  "synthid": true
}

Error Handling

Keep a comprehensive handler such as generate_image_safe(...) with retries.

Common pitfalls:

Rate Limits And Cost

Rate limits and image pricing vary by model, project, tier, resolution, and service changes. Read the live project quota and current official pricing page before production use; do not encode a static RPM/RPD table as a durable contract.

Rules:

• preview 1-3 images before large batches

Batch Guidance

For batch generation:

• generate sequentially with delay and retries
• show progress
• keep output paths deterministic
• estimate total cost before the run

SynthID

All Gemini-generated images contain an invisible SynthID watermark.

Document:

• that the image is AI-generated
• the model used
• the generation timestamp
• that SynthID is present

Suggested disclosure snippet:

This image was generated using Google Gemini API.
It contains an invisible SynthID watermark for AI-generated content identification.
Model: gemini-3.1-flash-image
Generated: [timestamp]

Model Landscape and SDK Constraints (SKILL.md excerpt)

Silent-Failure Diagnostic Sequence (SKILL.md excerpt)

• Classify silent failures into four states before diagnosing: (1) prompt-side blocking (safety filter rejects the input), (2) output-side image blocking (IMAGE_SAFETY or blockReason), (3) no image produced (text-only response), (4) non-policy failures (ambiguous prompt, request-shape mistake). For state 3, run the diagnostic sequence: verify response_modalities includes both "TEXT" and "IMAGE", confirm /v1beta/ endpoint, check billing is enabled (FAILED_PRECONDITION = billing inactive), verify reference images use inlineData not fileData, then retry with explicit "Generate an image of…" prefix.