Image Handling

Image Handling Skill

Right format, right size, right quality. Staleness Watch: See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence

Format Selection

Conversion Commands

# SVG to PNG using sharp-cli (recommended)
# --density sets DPI for vector rendering (150 = crisp text)
npx sharp-cli -i input.svg -o output-folder/ --density 150 -f png

# Note: output must be a directory, filename preserved from input
npx sharp-cli -i banner.svg -o assets/ --density 150 -f png
# Creates: assets/banner.png

# ImageMagick (if installed)
magick input.svg -resize 512x512 output.png
magick input.png -quality 85 output.jpg

# Multiple sizes
foreach ($size in 16,32,64,128,256,512) {
  magick input.svg -resize ${size}x${size} "icon-$size.png"
}

SVG to PNG Tips

• Emojis don't convert well - Use text-only or SVG icons
• Use --density 150+ for crisp text rendering
• Check file size - README banners should be < 500KB

GitHub README Images

<!-- Absolute URL (always works) -->

![Banner](https://raw.githubusercontent.com/user/repo/main/assets/banner.svg)

<!-- Relative (works in repo) -->

![Banner](./assets/banner.png)

<!-- With dark/light variants -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="banner-dark.svg">
  <img src="banner-light.svg" alt="Banner">
</picture>

Size Guidelines

Optimization

# PNG optimization
pngquant --quality=65-80 input.png -o output.png

# JPEG optimization
jpegoptim --max=85 input.jpg

# SVG optimization
npx svgo input.svg -o output.svg

Visual Verification (VS Code 1.112+)

After generating or converting images, use view_image to verify output quality:

For batch operations, use VS Code's image carousel to compare multiple outputs side-by-side.

Batch Processing

# Convert all PNGs in a folder (cross-platform)
for f in *.png; do magick "$f" -resize 256x256 "resized-$f"; done

# macOS -- sips (zero-install, ships with macOS)
sips -Z 256 *.png                          # Resize to max 256px
sips -s format jpeg input.png --out out.jpg # Convert PNG to JPEG
sips -g pixelHeight -g pixelWidth image.png # Read dimensions

macOS sips (Scriptable Image Processing System)

macOS ships sips -- zero install, always available. Use for quick resize, format conversion, and metadata reads.

Limitations: No SVG rendering, no compositing, no layering, no text overlay. For those, use ImageMagick or Inkscape.

Replicate Model Selection

Match user intent to the right model. When a user names a specific model or describes a need, use this table.

Model Selection Guide

• "quick" / "test" / "prototype" → Flux Schnell ($0.003, 4 steps)
• "high quality" / "production" → Flux 1.1 Pro ($0.04) or Flux 2 Pro for multi-ref
• Text must appear in the image → Ideogram v3 Turbo ($0.03) or v3 Quality ($0.09); v2 still works
• Simple/fast text in image → Ideogram v3 Turbo ($0.03, fastest + cheapest)
• Edit an existing image → Flux Kontext Pro ($0.04, text-prompted editing)
• Premium image editing → Flux Kontext Max ($0.08, better typography in edits)
• Painting style / custom LoRA → SDXL or Flux Dev with LoRA weights
• Largest / highest resolution output → Seedream 5 Lite (up to 3K) or Nano-Banana Pro (up to 4K)
• README banner (default, SVG) → Recraft v4 SVG (recraft-ai/recraft-v4-svg, native SVG output, scalable); see ai-generated-readme-banners skill
• README banner (premium SVG) → Recraft v4 Pro SVG ($0.30, detailed vector paths)
• README banner (raster, with text) → Ideogram v3 Turbo 3:1 ratio ($0.03)
• README banner (raster, no text) → Flux 1.1 Pro with 21:9 ratio
• Face-consistent portraits (fast) → Nano-Banana 2 ($0.067/1K, image_input array, same API as Pro)
• Face-consistent portraits (quality) → Nano-Banana Pro ($0.025, image_input up to 14 refs)
• Multi-reference high quality → Flux 2 Pro (~$0.05+, input_images up to 8 refs) or Flux 2 Flex (up to 10 refs)
• Highest fidelity → Flux 2 Max
• Character consistency (single ref) → Ideogram Character
• Google flagship → Imagen 4 (standard), Imagen 4 Ultra (highest quality), Imagen 4 Fast (budget)
• Sub-second real-time → Flux 2 Klein 4B (distilled, 10M+ runs)
• Vector/SVG logo or graphic → Recraft v4 SVG (native SVG output) or Recraft v4 Pro SVG ($0.30)
• Art-directed design → Recraft v4 (strong composition, design taste)
• Short video clip (≤8s) → Veo-3.1-fast (faster/cheaper successor to Veo-3, auto audio)
• Longer video (≤15s) → Grok Video (xai/grok-imagine-video, $0.05/sec, auto audio + lip-sync)
• Cinematic video → Kling v3 (kwaivgi/kling-v3-video, 1080p, multi-shot, ≤15s)
• Realistic home-video quality → Sora-2 (openai/sora-2, synced audio)

LoRA Support (Flux Dev / SDXL)

Both Flux Dev and SDXL accept LoRA weights:

// Replicate format
extra_lora: "fofr/flux-pixar-cars";
// HuggingFace format
extra_lora: "huggingface.co/owner/model-name";
// CivitAI format
extra_lora: "civitai.com/models/<id>";
// Direct URL
extra_lora: "https://example.com/weights.safetensors";

Aspect Ratio Reference

Face Reference Models

For character/portrait consistency across multiple generations, use models that accept reference images:

Nano-Banana Pro (Recommended for Portraits)

const output = await replicate.run("google/nano-banana-pro", {
  input: {
    prompt: "Description of desired scene",
    image_input: referenceImageURIs, // Array of data URIs (up to 14)
    aspect_ratio: "3:4",
    output_format: "png",
  },
});

Key: image_input accepts an array of data URIs. More references = better face consistency.

Flux 2 Pro (Higher Quality Alternative)

const output = await replicate.run("black-forest-labs/flux-2-pro", {
  input: {
    prompt: "Description of desired scene",
    input_images: referenceImageURIs, // Array of data URIs (up to 8)
    aspect_ratio: "3:4",
    output_format: "png",
  },
});

Key: input_images (not image_input) — different parameter name from nano-banana.

Preparing Reference Photos

# Resize to 512px @ 85% quality for optimal API performance
magick input.jpg -resize 512x512 -quality 85 output.jpg

# Convert to base64 data URI (for embedding in visual memory)
[Convert]::ToBase64String([IO.File]::ReadAllBytes("photo.jpg")) | Set-Clipboard

Optimal reference specs: 512px longest edge, 85% JPEG quality, ~40-80KB per photo.

Video Generation Models

Generate video from a still image or text prompt via Replicate. All video models support image-to-video workflows.

Duration Constraints

Video Generation Pattern

Typical workflow: generate a still image first, then animate it:

// Step 1: Generate still image
const image = await replicate.run("google/nano-banana-pro", {
  input: { prompt: "Person smiling at camera", image_input: refs },
});

// Step 2: Animate to video
const video = await replicate.run("google/veo-3", {
  input: {
    prompt: "Head turns slowly, smile widens, warm natural lighting",
    image: imageUrl,
    duration: 6,
  },
});

Cloud TTS Models (Replicate)

For content creation (audiobooks, narration, voice cloning), Replicate offers paid cloud TTS models.

Voice Presets

Speech Turbo: Wise_Woman, Deep_Voice_Man, Casual_Guy, Lively_Girl, Young_Knight, Abbess, + 6 more Chatterbox: Andy, Luna, Ember, Aurora, Cliff, Josh, William, Orion, Ken Qwen TTS: Aiden, Dylan, Eric, Serena, Vivian, + 4 more

Emotion Control (Speech Turbo)

Supported emotions: auto, happy, sad, angry, fearful, disgusted, surprised

Voice Cloning (Chatterbox / Qwen)

Provide a 5+ second audio sample to clone a voice:

const output = await replicate.run("resemble-ai/chatterbox-turbo", {
  input: {
    text: "Content to speak in the cloned voice",
    audio_prompt: referenceAudioDataURI, // 5+ seconds WAV/MP3
  },
});

Voice Design (Qwen TTS)

Create a voice from a natural language description:

const output = await replicate.run("qwen/qwen3-tts", {
  input: {
    text: "Content to speak",
    tts_mode: "voice_design",
    voice_description:
      "A warm, friendly female voice with a slight British accent",
  },
});

When to Use Each TTS Model