Immich API Bridge
Configuration
Option 1: Environment Variables
Windows (PowerShell):
$env:IMMICH_URL = "https://your-immich-instance.com"
$env:IMMICH_API_KEY = "your-api-key-here"
Linux/macOS (bash):
export IMMICH_URL="https://your-immich-instance.com"
export IMMICH_API_KEY="your-api-key-here"
Generate API Key in Immich: User Profile → API Keys → Create API Key
Option 2: CLI Arguments
python scripts/upload_photos.py --url "https://your-immich.com" --api-key "your-key" --folder ./photos
python scripts/download_album.py --url "https://your-immich.com" --api-key "your-key" --album-id "abc123" --output ./downloads
Quick Start
Authentication
# Test connection
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server-info/ping"
Base URL
{IMMICH_URL}/api
Common Operations
Albums
# List albums
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums"
# Create album
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
-d '{"albumName":"My Album"}' "$IMMICH_URL/api/albums"
# Get album assets
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums/{albumId}"
Assets
# Get all assets (paginated)
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/assets?limit=100"
# Upload asset
curl -X POST -H "x-api-key: $IMMICH_API_KEY" \
-F "file=@/path/to/photo.jpg" \
"$IMMICH_URL/api/assets"
# Get thumbnail
curl -H "x-api-key: $IMMICH_API_KEY" \
"$IMMICH_URL/api/assets/{assetId}/thumbnail?format=jpeg" -o thumb.jpg
# Get original file
curl -H "x-api-key: $IMMICH_API_KEY" \
"$IMMICH_URL/api/assets/{assetId}/original" -o original.jpg
Users
# List users
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/users"
# Get current user
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/user/me"
Search
# Search assets
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
-d '{"query":"beach","take":10}' "$IMMICH_URL/api/search/assets"
Libraries
# List libraries
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/libraries"
# Scan library
curl -X POST -H "x-api-key: $IMMICH_API_KEY" \
"$IMMICH_URL/api/libraries/{libraryId}/scan"
Jobs
# Get job statuses
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/jobs"
# Trigger job (e.g., thumbnail generation)
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
-d '{"jobName":"thumbnail-generation","force":true}' "$IMMICH_URL/api/jobs"
Script Usage
Use the bundled scripts in scripts/ for complex operations:
upload_photos.py- Bulk upload photosdownload_album.py- Download entire albumsync_library.py- Sync external library
See references/api-endpoints.md for complete endpoint reference.
