DEV Community

Alex Spinov
Alex Spinov

Posted on

Immich Has a Free API: Self-Hosted Google Photos Alternative with Full REST API

#selfhosted #opensource #tutorial #webdev

What is Immich?

Immich is a self-hosted photo and video management platform — a Google Photos alternative. It features face recognition, map view, album sharing, machine learning search, and a comprehensive REST API.

1M+ GitHub stars. One of the most popular self-hosted projects in 2026.

Quick Start 

mkdir immich && cd immich
wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget https://github.com/immich-app/immich/releases/latest/download/.env
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Open http://localhost:2283 — your personal Google Photos.

The REST API 

export IMMICH_URL="http://localhost:2283/api"
export IMMICH_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode

Upload Photos 

curl -X POST "$IMMICH_URL/assets" \
  -H "x-api-key: $IMMICH_KEY" \
  -F "assetData=@photo.jpg" \
  -F "deviceAssetId=photo-001" \
  -F "deviceId=cli" \
  -F "fileCreatedAt=2026-03-28T10:00:00Z" \
  -F "fileModifiedAt=2026-03-28T10:00:00Z"
Enter fullscreen mode Exit fullscreen mode

Search Photos 

# Text search (ML-powered)
curl -X POST "$IMMICH_URL/search/smart" \
  -H "x-api-key: $IMMICH_KEY" \
  -d '{"query": "sunset on the beach"}'

# Search by metadata
curl -X POST "$IMMICH_URL/search/metadata" \
  -H "x-api-key: $IMMICH_KEY" \
  -d '{
    "takenAfter": "2026-01-01",
    "takenBefore": "2026-03-28",
    "city": "Paris"
  }'
Enter fullscreen mode Exit fullscreen mode

Albums 

# Create album
curl -X POST "$IMMICH_URL/albums" \
  -H "x-api-key: $IMMICH_KEY" \
  -d '{"albumName": "Vacation 2026"}'

# Add photos to album
curl -X PUT "$IMMICH_URL/albums/ALBUM_ID/assets" \
  -H "x-api-key: $IMMICH_KEY" \
  -d '{"ids": ["ASSET_ID_1", "ASSET_ID_2"]}'

# Share album
curl -X PUT "$IMMICH_URL/albums/ALBUM_ID/users" \
  -H "x-api-key: $IMMICH_KEY" \
  -d '{"sharedUserIds": ["USER_ID"]}'

# List albums
curl -s "$IMMICH_URL/albums" \
  -H "x-api-key: $IMMICH_KEY" | jq '.[].albumName'
Enter fullscreen mode Exit fullscreen mode

People (Face Recognition) 

# List recognized people
curl -s "$IMMICH_URL/people" \
  -H "x-api-key: $IMMICH_KEY" | jq '.people[] | {name, thumbnailPath}'

# Get person's photos
curl -s "$IMMICH_URL/people/PERSON_ID/assets" \
  -H "x-api-key: $IMMICH_KEY" | jq '.[].originalPath'
Enter fullscreen mode Exit fullscreen mode

Statistics 

curl -s "$IMMICH_URL/server-info/statistics" \
  -H "x-api-key: $IMMICH_KEY"
# {"photos": 12345, "videos": 678, "usage": 45000000000}
Enter fullscreen mode Exit fullscreen mode

Download Assets 

curl -o photo.jpg "$IMMICH_URL/assets/ASSET_ID/original" \
  -H "x-api-key: $IMMICH_KEY"

curl -o thumbnail.jpg "$IMMICH_URL/assets/ASSET_ID/thumbnail" \
  -H "x-api-key: $IMMICH_KEY"
Enter fullscreen mode Exit fullscreen mode

Key Features

  • ML Search: Search photos by description ("dog on beach")
  • Face Recognition: Auto-group photos by person
  • Map View: See where photos were taken
  • Memories: "On this day" flashbacks
  • Sharing: Albums, links, partner sharing
  • Mobile Apps: iOS and Android auto-backup

Immich vs Google Photos

Feature Immich Google Photos
Free storage Unlimited 15 GB
Privacy Your server Google
Face recognition Yes Yes
ML search Yes Yes
API Full REST Limited
Sharing Yes Yes
Mobile backup Yes Yes

Need photo management automation or self-hosted solutions?

📧 spinov001@gmail.com
🔧 My tools on Apify Store

Google Photos or self-hosted? What's your pick?

Top comments (0)