config-hermes/skills/image-download/high-quality-image-downloader/SKILL.md

---
name: high-quality-image-downloader
description: Skill for downloading high-quality images from free stock photo websites with fallback strategies
---

## Purpose
Download high-resolution images from free stock photo websites (Pexels, Unsplash, etc.) with multiple fallback strategies when direct downloads fail.

## When to Use
- User requests high-quality images for reference, learning, or documentation
- Need to download multiple images from free stock photo sites
- Direct download methods fail due to website restrictions

## Prerequisites
- Internet connection
- Access to free stock photo websites
- Sufficient disk space for downloads

## Steps

### 1. Primary Download Strategy (Pexels)
```bash
# Navigate to temp directory
cd /tmp

# Try downloading from Pexels (most reliable)
curl -s "https://www.pexels.com/search/{search_query}/" \
  | grep -o 'https://images.pexels.com/photos/[^\"]*\.jpg\?auto=compress' \
  | head -{number_of_images} \
  | sed 's/\\?auto=compress//g' \
  | xargs -I {} curl -s -O {}
```

### 2. Secondary Download Strategy (Unsplash)
```bash
# If Pexels fails, try Unsplash
curl -s "https://unsplash.com/s/photos/{search_query}" \
  | grep -o 'https://images.unsplash.com/photo[^\"]*\.jpg' \
  | head -{number_of_images} \
  | xargs -I {} curl -s -O {}
```

### 3. Tertiary Download Strategy (Google Images)
```bash
# As last resort, try Google Images (may be blocked)
curl -s "https://www.google.com/search?q={search_query}&tbm=isch" \
  | grep -o 'https://[^\"]*\.jpg' \
  | head -{number_of_images} \
  | xargs -I {} curl -s -O {}

# Alternative: Use Bing Images
curl -s "https://www.bing.com/images/search?q={search_query}" \
  | grep -o 'https://[^\"]*\.jpg' \
  | head -{number_of_images} \
  | xargs -I {} curl -s -O {}
```

### 4. File Verification
```bash
# Verify downloaded files
ls -la /tmp/*.jpg | head -{number_of_images}
file /tmp/*.jpg | head -{number_of_images}
```

## Error Handling

## Error Handling

### Common Issues and Solutions:
1. **Website blocking requests**: Use different User-Agent headers
2. **Rate limiting**: Add delays between requests
3. **Incomplete downloads**: Retry failed downloads
4. **Wrong file formats**: Convert to standard formats
5. **WeChat sending failures**: Provide local file paths instead
6. **Large file sizes**: Use compressed formats (WebP) when possible

### Retry Logic:
```bash
# Retry failed downloads up to 3 times
for attempt in {1..3}; do
  if [ -s "filename.jpg" ]; then
    echo "Download successful"
    break
  else
    echo "Download failed, retrying ($attempt/3)"
    sleep 2
  fi
done

# Handle WeChat-specific failures
grep -q "Weixin send failed" error.log && {
  echo "WeChat sending failed. Files saved to /tmp/"
  ls -la /tmp/*.jpg
}
```

### Retry Logic:
```bash
# Retry failed downloads up to 3 times
for attempt in {1..3}; do
  if [ -s "filename.jpg" ]; then
    echo "Download successful"
    break
  else
    echo "Download failed, retrying ($attempt/3)"
    sleep 2
  fi
done
```


## Verification Steps
1. Check file sizes (should be > 1KB for valid images)
2. Verify file format with `file` command
3. Confirm expected number of files downloaded
4. Test image displayability
5. Verify WeChat sending capability (if applicable)
6. Check file sizes for WeChat compatibility


## WeChat Integration Notes
- Direct file sending to WeChat may time out due to large file sizes
- Use `MEDIA:/path/to/file` format for file sharing
- Consider file size limits (typically 20MB for images)
- If sending fails, provide file paths for user to access locally
- WebP format may not display properly in all WeChat clients


## Performance Tips
- Use parallel downloads for faster processing
- Cache successful search results
- Clean up failed downloads automatically
- Monitor disk space usage
- Use WebP format for smaller file sizes when possible

## Example Usage
```bash
# Download 10 high-quality back exercise images
cd /tmp
curl -s "https://www.pexels.com/search/back%20exercises/" \
  | grep -o 'https://images.pexels.com/photos/[^\"]*\.jpg\?auto=compress' \
  | head -10 \
  | sed 's/\\?auto=compress//g' \
  | xargs -I {} curl -s -O {}

# Verify downloads
ls -la /tmp/*.jpg | head -10
file /tmp/*.jpg | head -10

# If WeChat sending fails, provide local paths
echo "Files saved to /tmp/"
ls -la /tmp/*.jpg
```