/generate-image

name: generate-image
description: Generate and transform images using AI Gateway API. Use when the user asks to create, generate, produce, or transform images, or work with image generation.
allowed-tools: Bash, Read

Image Generation Skill

Generate images from text prompts and transform existing images using the AI Gateway API with support for multiple AI models including Google Gemini, Byteplus Seedream, and OpenAI GPT-Image.

Overview

This Skill enables Claude to generate images from text descriptions and transform existing images with AI-powered modifications. It uses the AI Gateway API which routes requests to appropriate providers based on the model selected.

Prerequisites

**Required Environment Variable:**

• `AI_GATEWAY_API_KEY`: Your AI Gateway API key

If this environment variable is not set, the scripts will fail with an error message asking you to provide it.

Quick Start

Generate an Image from Text

Use the bundled script to generate images from text descriptions:

python3 scripts/generate_image.py "A serene landscape with mountains and a lake at sunset, photorealistic style"

Transform an Existing Image

Apply transformations to existing images using reference URLs:

python3 scripts/transform_image.py "Make this image more vibrant and add dramatic lighting" "https://example.com/image.jpg"

Supported Models

Image Generation Models

| Model | Provider | Best For | |-------|----------|----------| | `google/gemini-3.1-flash-image-preview` | Google Vertex AI | Latest fast image generation with improved quality | | `google/gemini-3-pro-image-preview` | Google Vertex AI | High-quality photorealistic images | | `google/gemini-2.5-flash-image` | Google Vertex AI | Fast image generation | | `byteplus/seedream-4-5` | Byteplus Seedream | Creative artistic styles | | `byteplus/seedream-4-0` | Byteplus Seedream | General purpose image generation | | `openai/gpt-image-1` | OpenAI | Advanced image synthesis | | `openai/gpt-image-1-mini` | OpenAI | Quick image generation | | `openai/gpt-image-1.5` | OpenAI | Enhanced image synthesis | | `openai/gpt-image-2` | OpenAI | Latest generation, multi-aspect ratio support |

API Parameters

Image Generation

• `prompt` (required): Text description of the desired image
• `model` (required): Model to use for generation
• `images` (optional): Array of reference image URLs for image-to-image transformation
• `response_format` (optional): "url" (default) or "b64_json"
• `n` (optional): Number of images to generate (default: 1)
• `size` (optional): Image dimensions (e.g., "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536")
• `aspectRatio` (optional): Aspect ratio — alternative to `size`. Supported values: `"1:1"`, `"16:9"`, `"9:16"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"3:1"`, `"1:3"`
• `background` (optional, OpenAI models only): `"transparent"` | `"opaque"` | `"auto"` — controls background transparency
• `user` (optional): User identifier for tracking

OpenAI gpt-image-2 / gpt-image-1.5 Parameters

These models support the full parameter set above. Key notes:

• Supports all aspect ratios via `aspectRatio` field
• Supports `background: "transparent"` for PNG output with transparency
• Use `response_format: "b64_json"` to receive raw image data; use `"url"` for a hosted URL
• Image editing (passing `images`) routes to the `/images/edits` endpoint automatically

Bundled Scripts

1. generate_image.py

Generate images from text prompts with customizable parameters.

**Usage:**

python3 scripts/generate_image.py "prompt" [--model MODEL] [--output OUTPUT] [--format FORMAT]

**Options:**

• `--model`: Model to use (default: google/gemini-3.1-flash-image-preview)
• `--output`: Output file path (default: generated_image.png)
• `--format`: Response format - "url" or "b64_json" (default: b64_json)

**Example:**

python3 scripts/generate_image.py \
  "A futuristic city with flying cars at night, cyberpunk style" \
  --model "google/gemini-3.1-flash-image-preview" \
  --output "city.png"

2. transform_image.py

Transform existing images using AI with text instructions.

**Usage:**

python3 scripts/transform_image.py "prompt" "image_url" [--model MODEL] [--output OUTPUT]

**Example:**

python3 scripts/transform_image.py \
  "Make this image more vibrant and add dramatic sunset lighting" \
  "https://example.com/original.jpg" \
  --output "enhanced.png"

3. batch_generate.py

Generate multiple images in batch.

**Usage:**

python3 scripts/batch_generate.py prompts.txt [--model MODEL]

**Example prompts.txt:**

A sunset over the ocean
A mountain landscape at dawn
A bustling city street at night

Implementation Notes

**When implementing image generation tasks:**

1. **Always use JavaScript for API calls** when writing custom code 2. **Check for API Key** at the start:

   const apiKey = process.env.AI_GATEWAY_API_KEY;
   if (!apiKey) {
     throw new Error('AI_GATEWAY_API_KEY environment variable is required. Please set it with your AI Gateway API key.');
   }

3. **Use the bundled Python scripts** for quick generation tasks rather than writing custom code

4. **Include Origin header** in all API requests: Set `Origin: https://trickle.so` header for proper request routing

5. **Handle both streaming and non-streaming responses** appropriately

6. **Save generated images** to appropriate file paths and inform the user

JavaScript Implementation Template

When you need to write custom JavaScript code for image generation:

const apiKey = process.env.AI_GATEWAY_API_KEY;
if (!apiKey) {
  throw new Error('AI_GATEWAY_API_KEY environment variable is required. Please set it with your AI Gateway API key.');
}

const API_BASE = `${process.env.AI_GATEWAY_BASE_URL}/api/v1`;

async function generateImage(prompt, model = 'google/gemini-3.1-flash-image-preview') {
  const response