Skip to main content
skill CX Codex

generate-image · happycapy-ai — Claude Code skill: what it does, how to install

generate-image generates images from text prompts and edits existing pictures via the AI Gateway API. Connects Claude Code to Gemini, Byteplus Seedream, and GPT-Image models.

MIT ★ 138 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add happycapy-ai/Happycapy-skills --skill generate-image -a claude-code
Open on GitHub

What generate-image does

The skill routes image creation and editing tasks through the AI Gateway API. It bundles three Python utilities: generate_image.py for prompt-based generation, transform_image.py for image-to-image changes via reference URLs, and batch_generate.py for processing lists of prompts from text files.

Supported backends include Google Vertex AI (gemini-3.1-flash-image-preview), Byteplus (seedream-4-5), and OpenAI (gpt-image-2, gpt-image-1.5). OpenAI endpoints support transparent PNG rendering with background: "transparent" and multiple aspect ratios from 1:1 to 16:9.

Every script fails without the AI_GATEWAY_API_KEY environment variable. Custom JavaScript implementations must also send the Origin: https://trickle.so header so the gateway can route calls correctly.

What it helps with

  • generate images from text descriptions using Gemini or GPT-Image
  • modify an existing image from a URL using text instructions
  • run batch image creation from a file containing multiple prompts
  • produce PNG assets with transparent backgrounds via OpenAI models

Example prompts for the agent

  • Generate a cyberpunk city at night using scripts/generate_image.py
  • Transform https://example.com/original.jpg to add dramatic sunset lighting
  • Run batch generation on prompts.txt with scripts/batch_generate.py

How to install generate-image

1Skills CLI (Vercel)

npx skills add happycapy-ai/Happycapy-skills --skill generate-image -a claude-code

2Manually: put the files in place

~/.claude/skills/generate-image/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/generate-image/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about generate-image

How to install generate-image in Claude Code?

Run npx skills add happycapy-ai/Happycapy-skills --skill generate-image -a claude-code in your terminal.

What does generate-image do?

It enables Claude Code to synthesize new graphics and modify existing images through the AI Gateway API using bundled Python automation scripts.

What is required to run generate-image?

You must provide the AI_GATEWAY_API_KEY environment variable. The bundled scripts stop immediately if the key is missing.

Source text

SKILL.md · MIT
---
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:

```bash
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:

```bash
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:**
```bash
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:**
```bash
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:**
```bash
python3 scripts/transform_image.py "prompt" "image_url" [--model MODEL] [--output OUTPUT]
```

**Example:**
```bash
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:**
```bash
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:
   ```javascript
   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:

```javascript
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 = await fetch(`${API_BASE}/images/generations`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
      'Origin': 'https://trickle.so'
    },
    body: JSON.stringify({
      model,
      prompt,
      response_format: 'url'
    })
  });

  if (!response.ok) {
    throw new Error(`API request failed: ${response.status} ${response.statusText}`);
  }

  return await response.json();
}

// Use the function
const result = await generateImage('A beautiful sunset over mountains');
console.log('Generated image URL:', result.data[0].url);
```

## Error Handling

All scripts include comprehensive error handling for:
- Missing API key
- Network failures
- Invalid responses
- File I/O errors

Errors will include helpful messages to guide troubleshooting.

## Best Practices

1. **Be Specific in Prompts**: Include style, mood, lighting, and composition details
2. **Use Appropriate Models**: Choose models based on your quality vs. speed requirements
3. **Reference Images**: Use image-to-image transformation for style transfer or modifications
4. **Batch Processing**: Use the batch script for multiple generations to save time
5. **Save Outputs**: Always specify meaningful output file names for organization

## Troubleshooting

### "AI_GATEWAY_API_KEY environment variable is required"
Set the environment variable before running scripts:
```bash
export AI_GATEWAY_API_KEY="your-api-key-here"
```

### Network Errors
Check your internet connection and verify the API Gateway is accessible.

### Invalid Model Errors
Ensure you're using a valid model name from the supported models list above.

## Additional Resources

For more details on API parameters and response formats, see the API documentation at the AI Gateway repository.

© happycapy-ai · MIT · happycapy-ai/Happycapy-skills

Similar skills

All skills for AI and ML →

generate-image by other authors comes first.

generate-image K-Dense-AI The generate-image skill for Claude Code generates and edits images via OpenRouter Image API with Gemini, Recraft, and Seedream, for artwork, logos, and concept art. CX Codex +1 2,200installs generate-image official github Generate images from text prompts with OpenAI or Google Gemini. Use it to create project textures, icons, sprites, artwork, or mockups. CX Codex +1 93installs generate-image OpenClaudia generate-image generates images from text prompts using OpenAI or Stability AI. Useful when your coding agent needs to create logos, banners, or illustrations directly in the project. CX Codex +1 360installs generate-image laurigates The generate-image skill generates images from text prompts using Google's Gemini 3 Pro Image model on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 177installs generate-image Sateezg generate-image turns a text request into a PNG file — icons, logos, banners, illustrations, mockups — by calling Claude-image-2 inside the Claude CLI already signed in on your machine. CX Codex +1 ★ 195repo stars image-gen Nick Nisi image-gen is a Claude Code skill that generates or edits images with Gemini or OpenAI. It handles illustrations, diagrams, and graphics with readable labels. CX Codex +1 ★ 114repo stars skill-image-gen official adamd9 skill-image-gen generates images from text prompts directly inside your editor. Useful when building game sprites, app icons, and mockups during coding. ★ 41,430repo stars mcp-image shinpr This MCP server creates or edits images through Gemini, OpenAI, or BytePlus Seedream, adding visual detail to short requests before generation. CX Codex +1 ★ 195repo stars Image Gen nuver-labs Image Gen lets coding agents produce and modify local image assets via Gemini and OpenAI. Helpful whenever a workflow requires UI mockups, logos, or banner drafts. CX Codex +1 ★ 1repo stars image-generation zc277584121 The image-generation skill creates illustrations, diagrams, and other visuals for articles and docs. It chooses between Codex, OpenAI API, and Gemini paths. CX Codex +1 4,000installs gpt-image-2 prime-skills Generates and edits images via OpenAI GPT Image 2 on RunComfy. Embeds text, logos, and multilingual typography accurately — for e-commerce, ads, and UI mockups. CX Codex +1 95,100installs

From the same set41

The whole set →
agent-1-issue-scout agent-1-issue-scout — a Claude subagent that scans pre-qualified GitHub repos for unclaimed good first issues and hands one scored pick to the next agent in the chain. CX Codex ★ 138repo stars html-over-markdown html-over-markdown generates self-contained HTML files with visual layouts, SVG diagrams, and interactive controls instead of plain Markdown. CX Codex +1 ★ 138repo stars contract-first-agents The contract-first-agents skill gives a multi-agent team a shared contract before parallel work begins, then checks the combined output. Use it when separate modules or document sections must fit together. CX Codex +1 ★ 138repo stars agent-9-status-monitor agent-9-status-monitor — a Claude subagent that polls your open pull requests, catches merges, closures, new reviews and CI failures, then updates the contribution history and alerts the other agents in the swarm. CX Codex ★ 138repo stars agent-0-strategic-planner The agent-0-strategic-planner subagent ranks GitHub issues by user impact and feasibility. Use it to find meaningful contribution opportunities instead of spending effort on cosmetic fixes. CX Codex ★ 138repo stars claude-code-templates Installs and drives the claude-code-templates CLI: a catalog of agents, slash commands, MCP servers, hooks and project templates for Claude, plus session monitoring. CX Codex +1 ★ 138repo stars 360-panorama-viewer 360-panorama-viewer builds a standalone HTML file with 360° panoramas rendered via Three.js. Useful for creating interactive VR galleries from local or generated equirectangular images. CX Codex +1 ★ 138repo stars agent-8-review-responder The agent-8-review-responder subagent tracks PR reviews and CI checks, handles simple feedback, and replies to reviewers. It escalates security concerns and changes that need human judgment. CX Codex ★ 138repo stars

Project sponsors

Companies that keep this analytics open