Image Embedding Size Limits

Image Embedding Size Limits

Category: Visual Time Saved: 30 minutes + token cost savings Battle-tested: Yes — AI context window management

The Problem

You're building an AI application that processes images — visual memory, document analysis, or character references. You embed images as base64 data URIs. Your context window fills up fast, API costs spike, or requests start failing.

Why It Happens

Base64 encoding increases image size by ~33%. A 512×512 image easily becomes 40-60KB of text. Put 10 images in context and you've used 500KB+ of your token budget.

The Rule

256px maximum for embedded images. Store originals at full resolution separately.

The 70% Savings

512px image: ~42KB base64
256px image: ~13KB base64
Savings: 70% per image

For 10 images: 420KB → 130KB — that's 290KB of context saved.

Implementation Pattern

Storage vs Embedding Split

// visual-memory.json
{
  "images": [
    {
      "id": "portrait-001",
      "name": "Character Reference",
      "storageSize": 512,      // Full resolution on disk
      "embedSize": 256,        // Smaller version in dataUri
      "storagePath": "assets/portraits/full/portrait-001.png",
      "dataUri": "data:image/png;base64,..."  // 256px version
    }
  ]
}

Resize on Embed

const sharp = require('sharp');

async function createEmbedding(imagePath, maxDim = 256) {
  const buffer = await sharp(imagePath)
    .resize(maxDim, maxDim, { fit: 'inside' })
    .png()
    .toBuffer();
  
  return `data:image/png;base64,${buffer.toString('base64')}`;
}

async function addToVisualMemory(imagePath, metadata) {
  // Store original at full resolution
  const storagePath = await copyToStorage(imagePath);
  
  // Create smaller embedding
  const dataUri = await createEmbedding(imagePath, 256);
  
  return {
    ...metadata,
    storageSize: 512,
    embedSize: 256,
    storagePath,
    dataUri,
  };
}

Lazy Loading Pattern

class VisualMemory {
  constructor() {
    this.index = [];  // Metadata only, no images
  }
  
  // Load thumbnails for context (256px)
  async getEmbeddings(ids) {
    return ids.map(id => this.index[id].dataUri);
  }
  
  // Load full resolution when needed
  async getFullResolution(id) {
    const entry = this.index[id];
    return fs.readFileSync(entry.storagePath);
  }
}

Size Reference Table

When to Use Each Size

Format Considerations

// PNG: Lossless, larger, good for diagrams
await sharp(input).png().toBuffer();

// JPEG: Lossy, smaller, good for photos
await sharp(input).jpeg({ quality: 80 }).toBuffer();

// WebP: Best compression, broad support
await sharp(input).webp({ quality: 80 }).toBuffer();

Verification Checklist

• Embedded images max 256px
• Original files stored separately at full resolution
• embedSize field documents the embedded dimension
• Base64 size under 20KB per image
• Total embedded image budget tracked

Common Symptoms

• Context window exceeded with few images
• API costs higher than expected
• Slow response times from large payloads
• "Request too large" errors

Related Skills

• docs-decay-velocity — Managing evolving content