CaptionSmith - Support

Getting Started

Option 1: Subscription Mode (Recommended)

Start captioning right away without managing API keys:

Try for free:
- macOS: 25 free captions
- iOS: 5 free captions
Subscribe for more:
- Basic: 50 captions/month
- Pro: 200 captions/month
- Unlimited: Unlimited captions
Process photos:

On macOS:
1. Open CaptionSmith
2. Click Select Folder and choose a folder with images
3. Choose a caption template
4. Click Process Images
On iOS/iPadOS:
1. Open CaptionSmith
2. Tap the + button to select photos from your library
3. Choose a caption template
4. Tap Process Images
5. Review and edit captions as needed
6. Tap Export and choose:
  - Save to Camera Roll - Saves captioned photos back to Photos library
  - Share Photos - Share via Messages, Mail, AirDrop, etc.

Option 2: Power User Mode (Use Your Own API Keys)

For high-volume users who want to use their own API credits:

Get an API Key from one of these providers:
- Claude (Anthropic): console.anthropic.com
- OpenAI: platform.openai.com
- Google Gemini: aistudio.google.com
Add Your API Key:

On macOS:
1. Open CaptionSmith
2. Go to Settings (Cmd+,)
3. Toggle Use Subscription Mode off
4. Select the API Keys tab
5. Paste your full API key into the appropriate field
6. Click Save Keys
On iOS/iPadOS:
1. Open CaptionSmith
2. Tap the Settings button (gear icon)
3. Toggle Use Subscription Mode off
4. Select the API Keys tab
5. Paste your full API key into the appropriate field
6. Tap Save Keys
Process Your Photos:

On macOS:
1. Click Select Folder and choose a folder with images
2. Select your preferred AI provider
3. Choose a caption template
4. Click Process Images
5. Review and edit captions in the results panel
6. Click Export to save captioned files with customizable options
On iOS/iPadOS:
1. Tap + to select photos from your Photos library (or use the Share Extension from Photos app)
2. Select your preferred AI provider
3. Choose a caption template
4. Tap Process Images
5. Review and edit captions inline
6. Tap Export and choose how to save your captioned photos

Platform Differences

macOS

Import: Select folders from Finder or drag-and-drop
Workflow: Two-phase export with review panel
Export Options:
- Overwrite original files
- Create copies with suffix
- Generate XMP sidecar files only
- Choose custom export location
Free Trial: 25 captions
Settings: Cmd+, or CaptionSmith → Settings menu

iOS/iPadOS

Import:
- Select from Photos library (up to 100 photos)
- Use Share Extension from Photos, Safari, or Files app (JPEG, PNG, HEIC, GIF, WebP supported)
- Share Extension limit: 100 photos per action
Workflow: Simple process → edit → export flow
Export Options:
- Save to Camera Roll (preserves metadata)
- Share Photos (Messages, Mail, AirDrop, etc.)
Free Trial: 5 captions
Settings: Tap gear icon in app
Speed Toggle: Option to use faster AI model for quicker processing

Frequently Asked Questions

What's the difference between Subscription Mode and Power User Mode?

Subscription Mode: No API keys needed. Subscribe for a monthly caption quota or use your free trial credits.
Power User Mode: Bring your own API keys from Anthropic, OpenAI, or Google. Best for high-volume users who want direct control over API costs.

How do I check my subscription usage?

macOS: Open Settings (Cmd+,) to see your current usage and subscription tier
iOS/iPadOS: Tap the Settings button (gear icon) to see your current usage and subscription tier

What image formats are supported?

Full metadata embedding: JPEG, TIFF, HEIC, PNG
XMP sidecar only: DNG and other RAW formats

Where are captions stored?

Captions are embedded into:

EXIF UserComment
IPTC Caption/Abstract
TIFF ImageDescription
XMP sidecar file (for all formats)

These fields are read by Lightroom, Adobe Bridge, Apple Photos, and most photo management apps.

Are my photos uploaded anywhere?

Subscription Mode: Photos are sent to CaptionSmith's AI service for caption generation.
Power User Mode: Photos are sent only to your selected AI provider (Anthropic, OpenAI, or Google).

No photos are stored or used for training. All processing is done on-demand.

Where are my API keys stored?

API keys (in Power User Mode) are stored securely in your device's Keychain (macOS Keychain or iOS Keychain) and never leave your device. If you enable iCloud sync in Settings, your API keys will sync across all your devices using encrypted iCloud storage.

How do I import photos on iOS?

There are two ways to import photos on iOS/iPadOS:

From within CaptionSmith: Tap the + button to select up to 100 photos from your Photos library
Using the Share Extension (from other apps):

The Share Extension allows you to send photos directly to CaptionSmith from other apps:

From Photos app:
- Select up to 100 photos
- Tap the Share button (square with arrow pointing up)
- Scroll down and select CaptionSmith
- Photos are automatically imported into CaptionSmith
From Safari (saving web images):
- Long-press on an image
- Tap Share
- Select CaptionSmith
- Image is imported into CaptionSmith
From Files app:
- Select one or more images (up to 100)
- Tap the Share button
- Select CaptionSmith
- Images are imported into CaptionSmith
Supported formats:
- JPEG
- PNG
- HEIC/HEIF
- GIF
- WebP
Limits:
- Maximum 100 photos per share action
- A toast notification will show "X photos imported" when complete

What's the difference between macOS and iOS workflows?

macOS: Two-phase workflow - Process photos → Review/edit captions → Export with customizable file options (overwrite, create copies, XMP sidecars)
iOS/iPadOS: Simplified workflow - Process photos → Edit inline → Export directly to Photos library or share to other apps

Can I use the Speed vs Quality toggle?

iOS/iPadOS only: In Settings, you can enable Prefer Fast Model to use a faster AI model (Gemini Flash) for quicker processing. This is ideal for captioning large batches on mobile devices. This option is not available on macOS.

What are Caption Templates?

Caption templates control how the AI generates captions for your photos. CaptionSmith includes 12 professional built-in templates (Descriptive, Concise, Stock Commercial, Product, Travel, etc.) plus the ability to create custom templates with your own instructions for the AI.

Built-in templates are available on all platforms. Custom templates can be created on macOS and iPad, and will sync to iPhone via iCloud.

See the Caption Templates section for the full list of templates and how to create custom ones.

Does CaptionSmith sync my settings across devices?

Yes! When you're signed into the same Apple ID on multiple devices with iCloud enabled, CaptionSmith automatically syncs:

Custom caption templates
All settings (AI provider, GPS options, keyword settings, etc.)
API keys (encrypted)
Metadata profiles (creator, copyright, etc.)

Changes sync within seconds when devices are online. See the iCloud Sync section for more details.

Why isn't my DNG file being modified?

RAW files (including DNG) cannot have metadata embedded directly. Instead, an XMP sidecar file is created next to your image. This is the industry-standard approach used by Lightroom and other professional tools.

The app says "No API key configured"

If you're using Power User Mode, make sure you've:

Added your API key in Settings → API Keys
Clicked "Save Keys"
Selected the correct provider in the main window

If you want to use Subscription Mode instead, toggle it on in Settings.

Feature Details

Caption Templates

Caption templates control the style and structure of AI-generated captions. CaptionSmith includes 12 professional built-in presets plus the ability to create custom templates.

Built-in Templates

Descriptive - Detailed, comprehensive captions with full context
Concise - Brief, to-the-point descriptions
Stock Commercial - Commercial use captions optimized for Shutterstock/Adobe Stock
Stock Editorial - Editorial use captions for news and documentary content
Product - E-commerce and product photography captions
Real Estate - Property and architectural photography
Food - Culinary and food photography
Travel - Destination and travel photography
Portrait - People and portrait photography
Event - Events, celebrations, and gatherings
Artistic - Creative and artistic interpretations
Social Media - Short, engaging captions for social platforms

Using Templates

On macOS:

Click Select Folder to choose your images
In the caption options panel, click the Template dropdown
Select a built-in template or a custom template
Click Process Images

On iOS/iPadOS:

Tap + to select photos
Tap the Template dropdown at the top
Select a built-in template or a custom template
Tap Process Images

Creating Custom Templates (macOS and iPad Only)

Custom templates let you define exactly how the AI should caption your photos.

On macOS:

Open Settings (Cmd+,)
Select the Templates tab
Click + (Add New Template)
Fill in:
- Name: Give your template a descriptive name
- System Prompt: Instructions for the AI (e.g., "Write captions in first person with an adventurous tone")
- Max Words: Maximum caption length (optional)
Click Save
Your custom template now appears in the Template dropdown

On iPad:

Tap Settings (gear icon)
Select the Templates tab
Tap + (Add New Template)
Fill in the template details
Tap Save

On iPhone:

Custom template creation is not available on iPhone due to screen size constraints
You can use custom templates created on macOS or iPad (synced via iCloud)

Example Custom Template:

Name: "Travel Blog"
System Prompt: "Write engaging first-person captions for a travel blog. Include emotions, sensory details, and storytelling elements. Keep it conversational and inspiring."
Max Words: 150

iCloud Sync

CaptionSmith uses iCloud to automatically sync your settings, templates, and API keys across all your devices.

What Syncs

Custom caption templates - Templates you create on macOS or iPad
All settings - AI provider, GPS options, stock mode, keyword settings, etc.
API keys (Power User Mode) - Securely encrypted before syncing
Metadata profiles - Creator name, copyright info, IPTC fields

How It Works

iCloud sync is automatic when:

You're signed into the same Apple ID on all devices
iCloud is enabled on each device
You have an internet connection

To verify iCloud is working:

On macOS:

System Settings → Apple ID → iCloud → Check that iCloud Drive is ON
In CaptionSmith, changes to settings/templates automatically sync within seconds

On iOS/iPadOS:

Settings → [Your Name] → iCloud → Check that iCloud Drive is ON
In CaptionSmith, changes to settings/templates automatically sync within seconds

Sync behavior:

Changes sync within a few seconds when both devices are online
If a device is offline, changes sync when it reconnects
The most recent change always wins (last-write-wins)

Privacy & Security

API keys are Base64-encoded and stored in Apple's encrypted iCloud Key-Value Store
Photos are never synced - only settings and templates
All iCloud data is encrypted in transit and at rest
You can disable iCloud sync by turning off iCloud Drive in System Settings

Troubleshooting iCloud Sync

Settings/templates not syncing:

Verify you're signed into the same Apple ID on all devices
Check that iCloud Drive is enabled in System Settings
Ensure you have an internet connection
Try making a small change (e.g., toggle a setting) to trigger a sync
Wait up to 30 seconds for sync to propagate

API keys not syncing:

In Settings, verify the API key is saved (click/tap "Save Keys")
Toggle a setting to trigger a sync
On the other device, toggle Subscription Mode off/on to reload keys
If still not working, manually copy the API key to the other device

Troubleshooting

"Invalid API key" error

Ensure you pasted the complete API key
Check that your API key is active and has credits
Verify you selected the correct provider for your key

"Rate limit exceeded" error

Wait a few minutes and try again
Consider using a different AI provider
Process fewer images at once

Captions not appearing in Lightroom (macOS)

For JPEG/TIFF: Captions are embedded directly — re-import or sync metadata
For DNG/RAW: Look for the .xmp sidecar file next to your image
In Lightroom: Right-click → Metadata → Read Metadata from File

Photos exported from iOS aren't showing captions

On iOS/iPadOS, captioned photos are saved back to the Photos library with embedded metadata. To view the captions:

In Photos app: Swipe up on a photo → tap "Add a Caption" to see the embedded caption
When exporting from Photos: Metadata is preserved in the exported file
In third-party apps: Captions appear in EXIF/IPTC fields

Some photos disappeared when sharing on iOS

If you're sharing a large batch of photos (50+) and some don't appear:

Try sharing in smaller batches (25-30 photos at a time)
Use "Save to Camera Roll" instead of "Share Photos" for large batches
Check the error message at the top of the export screen

Subscription troubleshooting

"Usage limit reached" or "No captions remaining"

When you've used all captions in your current billing period:

Free Trial:
- macOS: 25 captions total (one-time)
- iOS: 5 captions total (one-time)
- To continue, subscribe to Basic, Pro, or Unlimited tier
Basic (50/month): Upgrade to Pro or Unlimited, or wait until next billing cycle
Pro (200/month): Upgrade to Unlimited, or wait until next billing cycle
Unlimited: No limits — if you see this message, try restarting the app or checking your subscription status

Check your usage:

macOS: Settings (Cmd+,) → See usage counter at top
iOS/iPadOS: Settings (gear icon) → See usage counter at top

"Free trial expired"

Your trial has been used up:

macOS: 25 captions have been generated
iOS: 5 captions have been generated

To continue:

Subscribe to a paid tier (Basic, Pro, or Unlimited)
Or switch to Power User Mode and use your own API keys

"Unable to verify subscription" or "Receipt validation failed"

If the app can't verify your App Store purchase:

Quick fixes:

Restart the app - Close completely and reopen
Check your internet connection - Receipt validation requires internet
Restore purchases:
- macOS: Settings → Subscription tab → Click "Restore Purchases"
- iOS/iPadOS: Settings → Subscription tab → Tap "Restore Purchases"
Sign out and back into App Store:
- macOS: System Settings → Apple ID → Sign out, then sign back in
- iOS: Settings → [Your Name] → Sign out, then sign back in

Still not working?

Wait 5-10 minutes for App Store servers to sync
Verify the subscription is active in your App Store account:
- macOS: App Store → Account (bottom left) → Subscriptions
- iOS: Settings → [Your Name] → Subscriptions
If subscription shows as active but app doesn't recognize it, contact support with your order number

Switching between Subscription Mode and Power User Mode

Switching to Power User Mode (BYOK):

Go to Settings
Toggle Use Subscription Mode off
Go to API Keys tab and add your API key
Click/Tap Save Keys
Select your preferred provider in the main window

Note: Your subscription usage counter will stop incrementing when using Power User Mode. Your subscription remains active but won't be charged for captions generated with your own API keys.

Switching back to Subscription Mode:

Go to Settings
Toggle Use Subscription Mode on
The app will resume using your subscription quota

Common issue: "App still says no API key configured"

Make sure you've clicked/tapped Save Keys after pasting your API key
Try toggling Subscription Mode off and on again
Restart the app

Common issue: "Usage not incrementing in Power User Mode" This is expected behavior. When using your own API keys, the app doesn't consume your subscription quota. Only switch to Subscription Mode if you want to use your monthly caption allowance.

Contact & Feedback

Report Issues: GitHub Issues
Feature Requests: GitHub Issues

System Requirements

macOS 14.0 (Sonoma) or later
iOS/iPadOS 17.0 or later
Internet connection for AI caption generation
Optional: API key from Anthropic, OpenAI, or Google (Power User Mode only)