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](https://unsplash.com/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:

```bash
UNSPLASH_ACCESS_KEY=your_unsplash_access_key_here
```

### 3. Rebuild and Restart

```bash
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](https://unsplash.com/documentation)
- [Unsplash License](https://unsplash.com/license)
- [Unsplash Guidelines](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines)

---

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