mcp server

gimage

apresai/gimagecommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 21, 2026

Gimage - AI-Powered Image Generation and Processing

Gimage is a powerful tool for generating AI images and processing them with ease. Built with pure Go for maximum portability.

Three Ways to Use Gimage

1. Command-Line Tool (CLI)

A single binary with zero dependencies for local image operations on your computer.

2. MCP Server for AI Assistants

Run as an MCP (Model Context Protocol) server for seamless integration with Claude Desktop and other AI assistants.

3. Cloud API (AWS Lambda)

Production-ready serverless REST API for web applications and remote processing.

What Can You Do with Gimage?

AI Image Generation

Generate stunning images from text prompts using Google Gemini, Vertex AI, or xAI Grok
Multiple AI models: Gemini Nano Banana 2.1 (default, native 4K, $0.0225-$0.0756/image), Gemini 3 Pro (native 4K), Gemini 3.1 Flash, Gemini 3.1 Flash Lite ($0.034/image, 1K only), Vertex AI presets (vertex-nano-banana*, vertex-flash*), and xAI Grok Imagine 2.0 ($0.015-$0.07/image) plus Grok speed tier ($0.02/image)
Control size, style, quality, and aspect ratio
Reproducible results with seed values on providers that support seeds
Provider-specific features: output format (Vertex AI), native resolution (Gemini Nano Banana 2.1 / Gemini 3+ / Grok), aspect ratio (Grok 16 values), reference-image editing (Gemini, Vertex, Grok)
Batch generation: create multiple images at once

Image Processing

Resize - Change image dimensions while preserving aspect ratio (crop or fit)
Scale - Scale images by factor (2x, 0.5x, etc.)
Crop - Extract specific regions from images
Compress - Reduce file size while maintaining quality
Convert - Transform between formats (PNG, JPG, WebP, GIF, TIFF, BMP)

Batch Processing (MCP Server Only)

Process multiple images concurrently via MCP server
Optimized for AI assistants (Claude Desktop)
CLI users: use shell scripts or find + xargs

Integration Options

Claude Desktop: Run as MCP server
Web Applications: REST API via AWS Lambda
Serverless: AWS Lambda on ARM64/Graviton2

Quick Start - CLI

1. Installation

Homebrew (macOS/Linux) - Recommended

# Install gimage (tap is added automatically)
brew install apresai/tap/gimage

Upgrade via Homebrew

brew upgrade apresai/tap/gimage

Manual Installation

Prefer Homebrew when you can. Otherwise download the archive for your platform from the latest release, extract it, and put gimage on your PATH:

# Example: macOS Apple Silicon (asset names include the version, e.g. gimage_1.2.150_Darwin_arm64.tar.gz)
gh release download --repo apresai/gimage --pattern '*Darwin_arm64.tar.gz'
tar -xzf gimage_*_Darwin_arm64.tar.gz
chmod +x gimage
sudo mv gimage /usr/local/bin/

Other common patterns: *Darwin_x86_64.tar.gz, *Linux_x86_64.tar.gz, *Linux_arm64.tar.gz, *Windows_x86_64.tar.gz. Archives also include gimage-deploy on supported platforms.

2. Setup Authentication

Quick Start (recommended for most users):

# Get a Gemini API key from https://aistudio.google.com/app/apikey
# Then run the interactive setup:
gimage auth setup gemini

# Or use environment variable (more secure):
export GEMINI_API_KEY="your-api-key-here"
gimage generate "test sunset"

Check your configuration:

# Check current authentication status
gimage auth status

# List all configured providers with pricing
gimage auth list

# Test your credentials
gimage auth test gemini

Get API Keys:

Gemini API: https://aistudio.google.com/app/apikey (Gemini Nano Banana 2.1 $0.0225-$0.0756/image, Gemini Flash Lite $0.034/image, Gemini 3 Pro $0.134/image)
Vertex AI: https://cloud.google.com/vertex-ai (3 auth modes: Express Mode/Service Account/Application Default Credentials)
xAI Grok: https://console.x.ai (Grok Imagine 2.0 $0.015-$0.07/image; speed tier $0.02/image)

3. Generate Your First Image

gimage generate "a sunset over mountains with vibrant colors"

That's it! Your image will be saved as generated_<timestamp>.png

Examples

Image Generation

# Basic generation (positional prompt - most common)
gimage generate "futuristic city at night"

# Specify size and style
gimage generate "abstract art" --size 1024x1024 --style photorealistic

# Use Gemini Nano Banana 2.1 via Vertex (auto-detects vertex API)
gimage generate "beautiful landscape" --model vertex-nano-banana

# State exclusions directly in the prompt
gimage generate "forest scene with no people, no buildings"

# Reproducible results with seed (Gemini 3 Pro / 3.1 Flash)
gimage generate "random pattern" --model gemini-3-pro --seed 12345

# Generate multiple images at once
gimage generate "fantasy landscape" --count 3

# Use aspect ratio with Gemini Nano Banana 2.1 (1:1, 16:9, 9:16, 4:3, 3:4, 5:4, 4:5, 3:2, 2:3, 21:9, etc.)
gimage generate "wide landscape" --aspect-ratio 16:9

# Compositional editing with reference images (Gemini, Vertex, or Grok)
gimage generate "place this product on a marble counter, soft light" \
 --input-image product.png

# Grok image edit via xAI /images/edits (max 5 on Imagine 2.0; local path or https:// URL)
gimage generate "render this as a pencil sketch with detailed shading" \
 --model grok-quality --input-image photo.png --image-size 2K

# Grok edit from a public HTTPS reference (passed through to xAI)
gimage generate "make this neon cyberpunk" \
 --model grok --input-image https://example.com/photo.png

# Combine multiple references (character + scene) - caps: Grok 2.0=5, Grok Fast=3, Gemini Nano Banana 2.1 / 3 Pro / 3.1 Flash=14
gimage generate "this character in this environment, cinematic" \
 --input-image character.png --input-image scene.jpg

# Higher reasoning for complex layouts/text (Gemini Nano Banana 2.1 / Gemini 3+)
gimage generate "infographic 'Q3 +18%'" --image-size 4K --thinking high

# Google Search grounding for current/real visual references (Gemini Nano Banana 2.1 / Gemini 3+, billed per search)
gimage generate "official PlayStation 5 Slim front view" --grounding

# Control output format with Vertex AI (png, jpeg, webp)
gimage generate "portrait" --api vertex --output-format webp

# List all available models with pricing
gimage generate --list-models

# Or use explicit --prompt flag if preferred
gimage generate --prompt "your prompt here"

# Pro tip: Convert generated images to WebP for 90%+ size reduction
gimage generate "sunset over mountains" -o sunset.png
gimage convert --input sunset.png --format webp
# Or use cwebp directly for maximum control:
# cwebp -q 85 -mt -sharp_yuv -preset photo sunset.png -o sunset.webp

Tip: Always convert to WebP - AI-generated PNGs are typically 1-3 MB. Converting to WebP at quality 85 reduces file size by 90%+ with no visible quality loss. Use gimage convert --format webp or cwebp -q 85 -mt -sharp_yuv -preset photo for best results.

Image Processing

All image processing commands use explicit flags for clarity:

# Resize to specific dimensions (strictly preserves aspect ratio)
# --mode crop (default): fill target size, crop excess
# --mode fit: fit within target, may have borders
gimage resize --input photo.jpg --width 800 --height 600
gimage resize --input photo.jpg --width 800 --height 600 --mode fit

# Scale to 50% size
gimage scale --input photo.jpg --factor 0.5

# Crop a region
gimage crop --input photo.jpg --x 100 --y 100 --width 800 --height 600

# Compress with custom quality (supports JPG and WebP)
gimage compress --input photo.jpg --quality 85

# Convert format
gimage convert --input photo.png --format jpg

# Use --output to specify custom output path
gimage resize --input photo.jpg --width 800 --height 600 --output resized.jpg

# Add --verbose for detailed progress
gimage convert --input photo.png --format webp --verbose

Batch Processing

Batch operations are available only through the MCP server for use with AI assistants like Claude.

For CLI users who need batch processing:

Use shell scripts with loops
Use find + xargs for parallel processing
Example: find photos/ -name "*.jpg" | xargs -P 4 -I {} gimage resize --input {} --width 800 --height 600

MCP server batch tools (for AI assistants):

batch_resize - Concurrent image resizing
batch_compress - Concurrent compression
batch_convert - Concurrent format conversion

See MCP documentation for details.

Configuration

Authentication Priority (Highest to Lowest)

Command-line flags (highest priority)
Environment variables (GEMINI_API_KEY, VERTEX_API_KEY, etc.)
Config file (~/.gimage/config.md)
Default values (lowest priority)

Recommended: Use environment variables for sensitive keys. Config file stores keys in plaintext.

Config File

Location: ~/.gimage/config.md (created automatically by gimage auth commands)

Security Notes:

File permissions: 0600 (only you can read/write)
Contains PLAINTEXT API keys
NEVER commit to version control
PREFER environment variables over config file
Use gimage auth status to check for conflicting credentials

Format (markdown with **key**: value):

# Gimage Configuration

SECURITY WARNING
This file contains SENSITIVE API KEYS stored in PLAINTEXT.

**gemini_api_key**: your-gemini-key
**vertex_api_key**: your-vertex-key
**vertex_project**: your-gcp-project
**vertex_location**: global
**vertex_credentials_path**: /path/to/service-account.json
**grok_api_key**: xai-5zM...
**default_api**: gemini
**default_model**: gemini-nano-banana-2.1
**default_size**: 1024x1024
**log_level**: info

Environment Variables (Recommended)

Gemini API:

export GEMINI_API_KEY="your-key"

Vertex AI (3 authentication modes):

# Option 1: Express Mode (REST) - Simplest
export VERTEX_API_KEY="your-key"
export VERTEX_PROJECT="your-project-id"
export VERTEX_LOCATION="global"

# Option 2: Service Account - Production
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export VERTEX_PROJECT="your-project-id"

# Option 3: Application Default Credentials - gcloud SDK
# No env vars needed - uses gcloud auth

xAI Grok:

export GROK_API_KEY="xai-your-key"

Check credential conflicts:

gimage auth status # Shows which credentials are active and their sources

Available Models

Gemini API (Google AI Studio)

gemini-nano-banana-2.1 (default; gemini, nano-banana, nano-banana-2, nano-banana-2.1)
Pricing tiered by resolution: $0.0225 (0.5K), $0.0336 (1K), $0.0504 (2K), $0.0756 (4K)
Native 4K resolution, thinking (minimal, medium, high), Search grounding, up to 14 reference images
Best for: General-purpose high-quality generation at low cost
gemini-3-pro-image (gemini-3, gemini-3-pro)
Pricing: $0.134/image (1K/2K), $0.24/image (4K)
Native 4K resolution, sharp text rendering, deterministic seed support
Best for: Professional work, text-heavy images, diagrams, reproducible seeds
gemini-3.1-flash-image (gemini-3.1-flash, 3.1-flash)
Pricing tiered by resolution: $0.045 (0.5K), $0.067 (1K), $0.101 (2K), $0.151 (4K)
Native 4K resolution, seed support
Best for: High-quality images with deterministic seeds
gemini-3.1-flash-lite-image (flash, gemini-flash, gemini-lite)
Pricing: $0.034/image (1K only)
Thinking: minimal or high (no Search grounding)
Best for: High-volume, low-latency 1K drafts

Vertex AI (Google Cloud) - Paid

Vertex vertex-nano-banana* presets run Gemini Nano Banana 2.1 via generateContent; vertex-flash* presets run Gemini 3.1 Flash; vertex-flash-lite runs Gemini 3.1 Flash Lite. Options unsupported by the chosen provider are reported and ignored.

vertex-nano-banana (provider alias: vertex/nano-banana-2.1)
Pricing: resolution-tiered ($0.0225-$0.0756/image)
Medium thinking by default
Best for: Vertex-authenticated Gemini Nano Banana 2.1 workflows
vertex-nano-banana-fast (provider alias: vertex/nano-banana-2.1-fast)
Pricing: resolution-tiered ($0.0225-$0.0756/image)
Minimal thinking by default for faster generation
Best for: Quick iterations, batch processing
vertex-nano-banana-ultra (provider alias: vertex/nano-banana-2.1-ultra)
Pricing: resolution-tiered ($0.0225-$0.0756/image)
High thinking by default for best quality
Best for: Print-ready, marketing materials
vertex-flash / vertex-flash-fast / vertex-flash-ultra (provider aliases: vertex/flash-3.1*)
Pricing: resolution-tiered ($0.045-$0.151/image)
Medium / minimal / high thinking presets for Gemini 3.1 Flash via Vertex
vertex-flash-lite (provider alias: vertex/flash-3.1-lite)
Pricing: $0.034/image (1K only)
Minimal thinking by default
Best for: Cheap Vertex-authenticated drafts

xAI Grok - Paid

grok-imagine-image-2.0 (default Grok model / Quality Mode)
Pricing tiered by quality & resolution: $0.015 (low 1K), $0.03 (low 2K), $0.05 (medium 1K), $0.07 (medium 2K), $0.04 (auto 1K)
Optional --quality low|medium|auto
Supports aspect ratio (16 values including 21:9, 5:2, auto)
Supports image editing via --input-image (up to 5 refs: local path or https:// URL)
Optional --user for xAI end-user abuse monitoring
Best for: Current xAI image generation
Aliases: grok, grok-imagine, grok-quality, grok-imagine-quality, grok-imagine-image-quality, grok-imagine-pro, grok-imagine-image-pro, xai, aurora
grok-imagine-image (speed tier; alias grok-fast)
Pricing: $0.02/image (1K and 2K)
Supports aspect ratio and --input-image editing (max 3)
Best for: Fast Grok generations

View all models with live pricing:

gimage generate --list-models
# or
gimage auth list # Shows configured providers

Image Formats Supported

Input & Output: PNG, JPEG, WebP, GIF, TIFF, BMP

All processing operations preserve format by default, or you can specify output format with --output flag or use the convert command.

Advanced Features

Styles (Generation)

photorealistic - Realistic photos
artistic - Artistic interpretations
anime - Anime/manga style

Resize Modes

When resizing images, aspect ratio is always preserved:

crop (default) - Fill target dimensions, crop any excess
fit - Fit entire image within target, may have borders

# Crop mode: 800x600 output, excess cropped
gimage resize --input photo.jpg --width 800 --height 600 --mode crop

# Fit mode: image fits within 800x600, preserving full image
gimage resize --input photo.jpg --width 800 --height 600 --mode fit

Quality Settings

Compression quality: 1-100 (default: 90)
Resampling: Lanczos algorithm (highest quality)
Transparency: Preserved for PNG, white background for JPEG

Batch Processing (MCP Server Only)

Batch operations are available exclusively through the MCP server for AI assistants:

batch_resize - Concurrent image resizing
batch_compress - Concurrent compression
batch_convert - Concurrent format conversion

CLI users can use shell scripts with find + xargs for parallel processing.

Use Cases

For Designers & Artists

Rapid prototyping of visual concepts
Generate variations of ideas
Quick image editing and optimization
Batch resize for different platforms

For Developers

Generate placeholder images for apps
Automate image processing pipelines
Integrate AI generation into workflows
Test with reproducible images (seeds)

For Content Creators

Create social media graphics
Generate blog post illustrations
Batch optimize images for web
Convert formats for different platforms

For AI/ML Engineers

Generate training data
Create synthetic datasets
Automate image augmentation
Integrate with Claude via MCP server

MCP Server for AI Assistants

Gimage can run as an MCP (Model Context Protocol) server, enabling AI assistants like Claude to generate and process images directly. The server communicates over stdio using the MCP protocol and exposes 10 tools for image generation and processing.

Installation Methods

There are two ways to install gimage for use with Claude Desktop. Choose based on your use case:

Method 1: Homebrew (Recommended - macOS/Linux only)

Use this if: You want both CLI access AND MCP server functionality from a single installation.

Step 1: Install gimage via Homebrew

brew install apresai/tap/gimage
gimage --version # Verify installation

Step 2: Configure Claude Desktop MCP

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
 "mcpServers": {
 "gimage": {
 "command": "gimage",
 "args": ["serve"]
 }
 }
}

Why this method?

✓ Single installation serves both CLI and MCP
✓ Easy updates: brew upgrade apresai/tap/gimage
✓ Directly calls the gimage binary in your PATH
✓ Smaller total footprint (one binary)

Method 2: npm Package (Cross-platform alternative)

Use this if: You're on Windows, don't use Homebrew, or only want MCP functionality (no CLI needed).

Step 1: Install via npm

npm install -g @apresai/gimage-mcp

Step 2: Configure Claude Desktop MCP

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
 "gimage": {
 "command": "npx",
 "args": ["-y", "@apresai/gimage-mcp"]
 }
 }
}

Why this method?

✓ Works on Windows (Homebrew method doesn't)
✓ npm-based workflow (familiar to Node.js users)
✓ npx automatically downloads/runs the correct version
! Note: npm installs gimage ONLY for MCP use (hidden in npm global directory)
! If you want CLI access too, you'll need to install via Homebrew separately

Configuration difference explained:

Homebrew: Uses "command": "gimage" - directly calls the binary in your PATH
npm: Uses "command": "npx" - npx finds and runs the npm-installed package

Method 3: Claude Code

Use this if: You're using Claude Code CLI and want to add gimage as an MCP server.

Prerequisites: Install gimage via Homebrew first (see Method 1, Step 1).

One-command setup:

claude mcp add-json gimage '{"command": "gimage", "args": ["serve"]}'

That's it! Claude Code will now have access to all gimage MCP tools.

Setup Authentication

Before using the MCP server, configure your API credentials:

# Quick start with Gemini (most affordable)
gimage auth setup gemini

# Or use environment variable (more secure):
export GEMINI_API_KEY="your-api-key-here"

# Verify configuration
gimage auth status
gimage auth test gemini

The MCP server automatically uses credentials from:

Environment variables - GEMINI_API_KEY, VERTEX_API_KEY, GROK_API_KEY, etc. (RECOMMENDED for security)
Config file - ~/.gimage/config.md (created by gimage auth setup commands)

Best Practice: Use environment variables for production - they're more secure than storing credentials in config files.

Start Using with Claude

After installation and authentication, restart Claude Desktop. You can then use natural language:

"Generate an image of a sunset over mountains"
"Resize photo.jpg to 800x600"
"Compress all images in the photos directory to 85% quality"
"Create a high-resolution photorealistic image of a wise old wizard"

Available MCP Tools

The MCP server exposes 10 tools for AI assistants:

Tool	Purpose
`generate_image`	AI image generation from text
`resize_image`	Resize to specific dimensions
`scale_image`	Scale by factor (maintain aspect ratio)
`crop_image`	Crop to specific region
`compress_image`	Reduce file size with quality control
`convert_image`	Convert between formats
`batch_resize`	Resize multiple images concurrently
`batch_compress`	Compress multiple images
`batch_convert`	Convert multiple images to new format
`list_models`	List available AI models

Troubleshooting MCP Server

If the MCP server isn't working in Claude Desktop:

Verify gimage is installed and in PATH:

which gimage
gimage --version

Test the serve command directly:

gimage serve --verbose

This will show detailed logging to stderr. Press Ctrl+C to stop.

Verify API credentials are configured:

gimage auth status # Check all configured credentials

Test image generation works outside MCP:

gimage generate "test image"

Check Claude Desktop logs for error messages:

macOS: ~/Library/Logs/Claude/
Linux: ~/.config/Claude/logs/

Ensure config file exists and has correct permissions:

ls -la ~/.gimage/config.md

Should be readable (permissions: -rw------- or -rw-r--r--)

Environment Variables

The MCP server respects the same environment variables as the CLI. See Configuration for complete list of supported variables for all authentication modes (Gemini, Vertex AI, xAI Grok).

MCP Documentation

For comprehensive guides and examples:

Usage Guide: docs/MCP_USAGE.md - Complete setup and usage
Tool Reference: docs/MCP_TOOLS.md - Detailed tool documentation
Examples: docs/MCP_EXAMPLES.md - Real-world workflows
Implementation Plan: mcp.md - Complete MCP architecture and implementation details

Command Reference

See COMMANDS.md for complete command reference and detailed usage examples.

Available commands:

generate - AI image generation from text prompts
resize - Resize images to specific dimensions (with crop/fit modes)
scale - Scale images by a factor
crop - Crop images to specific regions
compress - Compress images to reduce file size (JPG, WebP)
convert - Convert images between formats
auth - Configure and manage API credentials (setup, status, list, test)
serve - Start MCP server for Claude Desktop (includes batch operations)
tui - Launch interactive terminal UI (supports all CLI options)

Removed commands (use alternatives):

batch - Use MCP server or shell scripts (see Batch Processing)
config - Use auth commands for configuration

Run gimage [command] --help for detailed usage of any command.

Interactive TUI

Launch the interactive Terminal User Interface for a guided image generation experience:

gimage tui

TUI Features:

Step-by-step image generation workflow (8 steps)
Provider selection with pricing and auth status
All CLI options available: size, style, seed, aspect ratio, image size, output format, resize mode, count
Command preview before generation
Progress tracking and error handling

Workflow Steps:

Enter your prompt
Select provider (Gemini, Vertex AI, Grok)
Choose image size
Select style (optional)
Configure advanced options
Set output path
Review command
Generate and view results

Go SDK

A type-safe Go SDK for programmatic API access.

Repository: github.com/apresai/gimage-go-sdk

Installation

go get github.com/apresai/gimage-go-sdk@latest

Quick Start

import gimage "github.com/apresai/gimage-go-sdk"

// Create client with API key authentication
client, _ := gimage.NewClient(
 "https://your-api.execute-api.us-east-1.amazonaws.com/production",
 gimage.WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
 req.Header.Set("x-api-key", "your-api-key")
 return nil
 }),
)

// Generate image
resp, _ := client.GenerateImage(ctx, gimage.GenerateImageJSONRequestBody{
 Prompt: "sunset over mountains",
 Model: stringPtr("gemini-nano-banana-2.1"),
 Size: stringPtr("1024x1024"),
})

Features

✓ Type-safe: All types generated from OpenAPI spec
✓ Auto-complete: Full IDE support with godoc
✓ API Gateway ready: Built-in API key authentication support
✓ Standard Go modules: Independent versioning with semantic versioning

Documentation

Complete documentation, examples, and API reference:

SDK Repository: github.com/apresai/gimage-go-sdk
GoDoc: pkg.go.dev/github.com/apresai/gimage-go-sdk
Examples: See the SDK repository for working examples

Lambda API Distribution

Deploy Gimage as a serverless REST API on AWS Lambda for web application integration.

Features

Serverless Architecture: AWS Lambda on ARM64/Graviton2 (provided.al2023 runtime)
Auto-Scaling: Handles 0 to thousands of requests automatically
Cost-Effective: Pay only for what you use (~$0.25/month for 10K requests)
S3 Storage: Automatic S3 bucket for image storage with presigned URLs
Production-Ready: Full CORS, error handling, monitoring
API Gateway Integration: Managed API keys, usage plans, rate limiting

Quick Deploy

Option 1: Using gimage-deploy tool (Recommended)

# Build Lambda function
make build-lambda
make package-lambda

# Deploy using gimage-deploy (from sibling directory)
cd ../gimage-deploy
./bin/gimage-deploy deploy \
 --id production \
 --stage production \
 --region us-east-1 \
 --lambda-code ../gimage/bin/lambda.zip \
 --memory 512 \
 --timeout 30

# Create API key
./bin/gimage-deploy keys create --name prod-key --deployment production

Option 2: Manual deployment

See the gimage-deploy directory for manual deployment with AWS CLI.

Deployment Tool

The gimage-deploy CLI tool (separate project) provides complete deployment management:

One-command deployment to AWS Lambda
API Gateway configuration with API keys
Monitoring (logs, metrics, health checks)
Interactive TUI for management
No hardcoded account IDs - works in any AWS account

See the gimage-deploy directory for the deployment management tool.

API Endpoints

All operations available via REST API:

Endpoint	Method	Purpose
`/generate`	POST	AI image generation
`/resize`	POST	Resize to dimensions
`/scale`	POST	Scale by factor
`/crop`	POST	Crop region
`/compress`	POST	Compress with quality
`/convert`	POST	Convert format
`/batch`	POST	Process multiple images
`/health`	GET	Health check
`/docs`	GET	Interactive Swagger UI documentation
`/openapi.yaml`	GET	OpenAPI specification

Try the API: After deployment, visit https://your-api-url/prod/docs for interactive documentation!

Integration Examples

TypeScript/JavaScript:

const response = await fetch("https://your-api-url/generate", {
 method: "POST",
 headers: { "Content-Type": "application/json" },
 body: JSON.stringify({
 prompt: "a sunset over mountains",
 size: "1024x1024",
 response_format: "s3_url",
 }),
});

const result = await response.json();
console.log("Image URL:", result.s3_url);

Python:

import requests

response = requests.post('https://your-api-url/resize', json={
 'image': base64_image,
 'width': 800,
 'height': 600
})

result = response.json()
print(f"Resized: {result['width']}x{result['height']}")

Go:

client := gimage.NewClient("https://your-api-url", apiKey)
result, err := client.GenerateImage(gimage.GenerateRequest{
 Prompt: "beautiful landscape",
 Size: "1024x1024",
})

Documentation

OpenAPI Spec: openapi.yaml - Complete API reference
Go SDK: github.com/apresai/gimage-go-sdk - Type-safe Go client

Architecture

Client Request → API Gateway → Lambda (Go/ARM64) → {S3, Gemini, Vertex AI, Grok}
 ↓
 Small: base64 response
 Large: S3 presigned URL

Runtime: AWS Lambda provided.al2023 (Amazon Linux 2023) Architecture: ARM64 (Graviton2 processors) Package Size: 17MB compressed, 42MB uncompressed Memory: 2GB (configurable) Timeout: 5 minutes max

Building from Source

CLI Binary

git clone https://github.com/apresai/gimage.git
cd gimage
make build
./bin/gimage --version

Lambda Function

# Build for AWS Lambda ARM64
make build-lambda

# Package as deployment zip
make package-lambda

# Output: bin/lambda.zip (17MB)

Requirements

CLI

None! Single static binary with zero dependencies
Works on: macOS, Linux, Windows (x86_64, ARM64)
No Python, no Node.js, no system libraries required

Lambda API

AWS Account
AWS CLI configured
Node.js 20+ (for CDK deployment)
Go 1.26+ (for building)

Support & Documentation

CLI

Full Command Reference: COMMANDS.md
Configuration Guide: See gimage auth --help

Lambda API

OpenAPI Specification: openapi.yaml

Community

GitHub Issues: https://github.com/apresai/gimage/issues
Discussions: https://github.com/apresai/gimage/discussions

License

MIT License - see LICENSE file for details.

Credits

Built with:

Cobra - CLI framework
golang.org/x/image - Pure-Go image processing
Google Gen AI SDK - Gemini & Vertex AI SDK

Built for developers, designers, and AI enthusiasts