opencode-gemini-image

An OpenCode plugin for generating, editing, analyzing, and extending images using Google's Gemini 3 Pro Image model.

Features

• Generate: Create images from text prompts with customizable aspect ratios and resolutions
• Edit: Modify existing images based on text instructions
• Analyze: Get detailed text descriptions of image content
• Extend: Outpaint images to expand their boundaries
• Character Consistency: Maintain consistent character appearance across multiple generations using session IDs and reference images

Installation

npm install opencode-gemini-image

Or using Bun:

bun install opencode-gemini-image

Configuration

The plugin requires two environment variables:

| Variable | Description | Required | |----------|-------------|----------| | GEMINI_API_KEY | Your Google Gemini API key | Yes | | GEMINI_API_ENDPOINT | The Gemini API endpoint URL | Yes |

Setting up environment variables

export GEMINI_API_KEY="your-api-key-here"
export GEMINI_API_ENDPOINT="https://generativelanguage.googleapis.com"

Or create a .env file in your project root:

GEMINI_API_KEY=your-api-key-here
GEMINI_API_ENDPOINT=https://generativelanguage.googleapis.com

Usage

The plugin provides a single gemini_image tool with multiple operation modes.

Generate Mode

Create images from text prompts:

const result = await gemini_image({
  mode: "generate",
  prompt: "A serene mountain landscape at sunset with snow-capped peaks",
  aspect_ratio: "16:9",
  resolution: "2K",
  output_path: "./landscape.png"
});

Edit Mode

Modify an existing image:

const result = await gemini_image({
  mode: "edit",
  prompt: "Add a golden retriever sitting in the foreground",
  input_image: "./landscape.png",
  output_path: "./landscape_with_dog.png"
});

Analyze Mode

Get a text description of an image:

const result = await gemini_image({
  mode: "analyze",
  prompt: "Describe the main subjects and their emotions",
  input_image: "./photo.png"
});
// Returns: "The image shows a smiling family of four at a beach..."

Extend Mode

Outpaint an image to expand its boundaries:

const result = await gemini_image({
  mode: "extend",
  prompt: "Extend the scene to show more of the sky and clouds",
  input_image: "./photo.png",
  output_path: "./photo_extended.png"
});

Character Consistency

Maintain consistent character appearance across generations:

// First generation - create a character
const result1 = await gemini_image({
  mode: "generate",
  prompt: "A young wizard with blue robes and a silver staff",
  session_id: "wizard-character-001",
  output_path: "./wizard_1.png"
});

// Subsequent generations - use the same session_id and reference_images
const result2 = await gemini_image({
  mode: "generate",
  prompt: "The same wizard casting a spell in a forest",
  session_id: "wizard-character-001",
  reference_images: ["./wizard_1.png"],
  output_path: "./wizard_2.png"
});

const result3 = await gemini_image({
  mode: "generate",
  prompt: "The same wizard reading a book in a library",
  session_id: "wizard-character-001",
  reference_images: ["./wizard_1.png", "./wizard_2.png"],
  output_path: "./wizard_3.png"
});

Parameter Reference

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mode | "generate" \| "edit" \| "analyze" \| "extend" | Yes | Operation mode | | prompt | string | Yes | Text prompt describing the operation | | input_image | string | For edit, analyze, extend | Path to input image file | | output_path | string | No | Path for output image (auto-generated if omitted) | | aspect_ratio | "1:1" \| "4:3" \| "3:4" \| "16:9" \| "9:16" \| "21:9" | No | Aspect ratio for generated images | | resolution | "1K" \| "2K" \| "4K" | No | Resolution for generated images | | reference_images | string[] | No | Array of paths to reference images for style guidance | | session_id | string | No | Session ID for maintaining character consistency |

Aspect Ratios

| Ratio | Dimensions (approximate) | Best For | |-------|-------------------------|----------| | 1:1 | Square | Social media posts, avatars | | 4:3 | 1024x768 | Standard photos, presentations | | 3:4 | 768x1024 | Portrait photos, mobile screens | | 16:9 | 1920x1080 | Widescreen, videos, desktops | | 9:16 | 1080x1920 | Mobile stories, vertical video | | 21:9 | 2560x1080 | Ultrawide, cinematic |

Resolutions

| Resolution | Approximate Size | Use Case | |------------|------------------|----------| | 1K | ~1024px | Quick previews, thumbnails | | 2K | ~2048px | Standard quality, web use | | 4K | ~4096px | High quality, print ready |

Error Handling

The plugin returns errors in a consistent format. Always check for errors in the result:

const result = await gemini_image({
  mode: "generate",
  prompt: "A beautiful sunset"
});

if (result.error) {
  console.error("Image generation failed:", result.error);
  // Handle error appropriately
}

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | Missing GEMINI_API_KEY environment variable | API key not set | Set the GEMINI_API_KEY environment variable | | Missing GEMINI_API_ENDPOINT environment variable | Endpoint not set | Set the GEMINI_API_ENDPOINT environment variable | | input_image is required for {mode} mode | Missing input image for edit/analyze/extend | Provide the input_image parameter | | No image in response | API returned no image | Retry the request or modify the prompt | | No text in response | API returned no text (analyze mode) | Retry the request or modify the prompt |

Types

type GeminiMode = "generate" | "edit" | "analyze" | "extend";

type AspectRatio = "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9";

type Resolution = "1K" | "2K" | "4K";

interface GeminiImageParams {
  mode: GeminiMode;
  prompt: string;
  input_image?: string;
  output_path?: string;
  aspect_ratio?: AspectRatio;
  resolution?: Resolution;
  reference_images?: string[];
  session_id?: string;
}

interface GeminiImageResult {
  file_path?: string;  // Path to generated image (generate, edit, extend modes)
  text?: string;       // Analysis result (analyze mode)
  error?: string;      // Error message if operation failed
}

License

MIT