Skip to main content

Quick Start: Batch Captions

Get batch caption processing running in 5 minutes.

1. Set Environment Variables​

Copy to your .env file:

# Choose ONE provider:

# Option A: Gemini (recommended - 10× cheaper)
AI_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-key-here
GEMINI_MODEL=gemini-1.5-flash

# Option B: OpenRouter (best quality)
# AI_PROVIDER=openrouter
# OPENROUTER_API_KEY=sk-or-v1-your-key-here
# AI_MODEL=openai/gpt-4o

# Option C: Mock (testing only - no API key needed)
# AI_PROVIDER=mock

# Batch settings (optional - these are defaults)
BATCH_MAX_SIZE=50
BATCH_TIMEOUT_MS=60000
AI_TIMEOUT_MS=15000

Get API Keys:

2. Start Server​

npm run server
# Server runs on http://localhost:4001

3. Use in Your Code​

Simple Batch Processing​

import { CaptionProvider } from 'photoswipe-pro/ai';

const provider = new CaptionProvider({ baseUrl: '/api/ai' });

// Process multiple images at once
const result = await provider.generateBatch({
  images: [
    { url: 'https://example.com/photo1.jpg' },
    { url: 'https://example.com/photo2.jpg' },
    { url: 'https://example.com/photo3.jpg' }
  ],
  licenseKey: 'your-photoswipe-pro-license-key'
});

// Use results
result.results.forEach(item => {
  if (!item.error) {
    console.log(`${item.url}: ${item.alt}`);
    // Update your UI with item.alt and item.caption
  }
});

console.log(`Success: ${result.summary.success}/${result.summary.total}`);

Auto-Batching Helper (for 50+ images)​

const urls = [
  'photo1.jpg',
  'photo2.jpg',
  // ... up to 1000s of images
];

const captionsMap = await provider.generateForUrls({
  urls,
  licenseKey: 'your-photoswipe-pro-license-key'
});

// Lookup results
urls.forEach(url => {
  const result = captionsMap.get(url);
  if (result) {
    console.log(`${url}: ${result.alt}`);
  }
});

4. Test It​

cd test
node batch-caption-test.js

Expected output:

==== Test 1: Single Image Caption ====
✓ Single caption successful

==== Test 2: Batch Caption (5 images) ====
✓ Batch caption successful
  Total: 5
  Success: 5
  Failed: 0
  Duration: 2341ms (468ms per image)

Results: 5/5 tests passed
✓ All tests passed!

API Endpoints​

Single Image​

POST /api/ai/caption
{
  "url": "https://example.com/photo.jpg",
  "licenseKey": "your-key"
}

Batch (1-50 images)​

POST /api/ai/caption/batch
{
  "images": [
    { "url": "photo1.jpg" },
    { "url": "photo2.jpg" }
  ],
  "licenseKey": "your-key"
}

Who Needs API Keys?​

WhoNeeds API Key?
You (server owner)✅ YES - Gemini or OpenRouter
Your users (website visitors)❌ NO
Client apps❌ NO - only PhotoSwipe Pro license

You pay for AI, users pay for PhotoSwipe Pro. Your server proxies all requests.

Troubleshooting​

"provider_disabled" error​

→ Set GEMINI_API_KEY or OPENROUTER_API_KEY in .env

"batch_too_large" error​

→ Max 50 images per request. Use generateForUrls() for auto-batching.

"rate_limited" error​

→ Default is 20 requests/min. Increase with AI_RATE_LIMIT_MAX=50

Images timing out​

→ Increase timeout: AI_TIMEOUT_MS=30000 (30 seconds)

Server not starting​

→ Check port 4001 is available: lsof -i :4001

Performance​

100 images:

  • Single requests: ~25 minutes
  • Batch requests: ~2 minutes
  • 12× faster!

Cost is the same - you pay per image, not per request.

Next Steps​

✅ Production: Set REQUIRE_LICENSE=true and use real API keys
✅ Documentation: See docs/batch-caption-guide.md
✅ Architecture: See docs/pro-ai-captions-architecture.md
✅ Full guide: See docs/BATCH-IMPLEMENTATION-COMPLETE.md

That's it! 🎉 You're now processing images 12× faster with batch captions.