voxblog/STOCK_PHOTOS_SETUP.md

Stock Photos Feature Setup

Overview

The Media Library now includes a Stock Photos tab that lets you search and import free high-quality photos from Unsplash directly into your library.

Features

✅ Search stock photos - Search Unsplash's library of millions of free photos ✅ Import to library - One-click import to your media library ✅ Proper attribution - Photographer credits included ✅ No manual download - Photos are fetched and uploaded automatically ✅ Seamless integration - Imported photos appear in your library instantly

Setup Instructions

1. Get Unsplash API Key

1. Go to Unsplash Developers
2. Sign up or log in
3. Click "New Application"
4. Accept the API terms
5. Fill in application details:
   • Application name: VoxBlog (or your blog name)
   • Description: Blog content management system
6. Copy your Access Key

2. Add API Key to Environment

Add the Unsplash API key to your .env file:

UNSPLASH_ACCESS_KEY=your_unsplash_access_key_here

3. Rebuild and Restart

docker-compose up -d --build

Usage

Search Stock Photos

1. Go to Assets step in post editor
2. Click Stock Photos tab in Media Library
3. Enter search term (e.g., "mountain sunset", "office desk", "coffee")
4. Click Search

Import Photos

1. Browse search results
2. Click Import to Library on any photo
3. Photo is downloaded and uploaded to your S3 storage
4. Automatically switches to My Library tab
5. Imported photo appears in your library

Use Imported Photos

Once imported, stock photos work exactly like your uploaded photos:

• Insert into content
• Set as feature image
• Copy URL
• Delete if needed

API Limits

Unsplash Free Tier

• 50 requests per hour (demo/development apps)
• 5,000 requests per hour (production apps - requires approval)

Rate Limit Guidelines

• Search requests count toward your limit
• Import requests count toward your limit
• Unsplash tracks downloads for photographer attribution

Production Approval

For production use with higher limits:

1. Go to your Unsplash app dashboard
2. Click "Request Production Access"
3. Provide app details and screenshots
4. Usually approved within 24-48 hours

Attribution

Unsplash requires attribution for photos. The feature automatically:

• ✅ Displays photographer name with link
• ✅ Tracks download for Unsplash analytics
• ✅ Includes UTM parameters for proper attribution

When using imported photos in your blog, consider adding photographer credit in the caption.

Technical Details

API Endpoints

Search:

GET /api/stock-photos/search?query=mountain&per_page=30

Import:

POST /api/stock-photos/import
Body: {
  photoId: string,
  downloadUrl: string,
  downloadLocation: string,
  photographer: string,
  photographerUrl: string
}

Storage

Imported photos are stored in S3 with the naming pattern:

images/YYYY-MM-DD/unsplash-{photoId}-{randomId}.{ext}

File Formats

Supported formats:

• JPEG (most common)
• PNG
• WebP
• GIF

Troubleshooting

"Unsplash API key not configured"

Solution: Add UNSPLASH_ACCESS_KEY to .env and rebuild containers

"Failed to search stock photos"

Possible causes:

• Invalid API key
• Rate limit exceeded
• Network connectivity issue

Solution: Check API key, wait if rate limited, verify network

"Failed to import photo"

Possible causes:

• S3 storage not configured
• Network timeout
• Invalid photo URL

Solution: Verify S3 credentials, check logs for details

Rate Limit Exceeded

Solution:

• Wait for rate limit to reset (hourly)
• Request production access for higher limits
• Cache search results on frontend

Best Practices

Search Tips

• Be specific: "laptop on wooden desk" vs "laptop"
• Use keywords: "minimal", "modern", "vintage", etc.
• Try variations: If no results, try synonyms

Import Strategy

• Import only what you need: Don't bulk import
• Review before importing: Check photo quality and relevance
• Organize after import: Use descriptive filenames

Attribution

• Add captions: Include photographer name in image captions
• Link to photographer: Use the provided photographer URL
• Follow Unsplash guidelines: https://unsplash.com/license

Example Searches

Good search terms:

• coffee cup workspace
• mountain landscape sunset
• modern office interior
• person working laptop
• food photography minimal
• abstract geometric pattern
• nature forest trees
• city skyline night

Future Enhancements

Potential improvements:

• Pagination for search results
• Filter by orientation (landscape/portrait)
• Filter by color
• Save favorite photographers
• Bulk import
• Search history
• Integration with other stock photo services (Pexels, Pixabay)

Resources

• Unsplash API Documentation
• Unsplash License
• Unsplash Guidelines

---

Status: ✅ Ready to use Last Updated: 2025-10-27 Version: 1.0