This is a RESTful photo management API that provides functionality for capturing, storing, listing, and deleting photos. The application also integrates with Immich (a self-hosted photo management service) for cloud backup and album organization.
The application requires the following environment variables:
Variable | Description | Required | Example |
---|---|---|---|
IMMICH_BASE_URL |
Base URL of your Immich instance | Yes | https://photos.example.com/api |
IMMICH_API_KEY |
API key for Immich authentication | Yes | your-immich-api-key |
IMMICH_ALBUM_ID |
Target album ID in Immich for uploads | Yes | album-uuid-here |
/
├── photos/ # Local photo storage directory
├── public/ # Static web files
│ └── index.html # Main web interface
├── index.js # Main application file
└── .env # Environment configuration
Endpoint: GET /
Description: Serves the main web interface for the photo management application.
Response: HTML page
Status Codes:
200
: Success - returns HTML interfaceEndpoint: GET /photos
Description: Retrieves a list of all stored photos in the local directory.
Request: No body required
Response:
[
"photo-1640995200000.png",
"photo-1640995260000.png",
"photo-1640995320000.png"
]
Status Codes:
200
: Success - returns array of filenames500
: Server error - failed to read photo directoryEndpoint: GET /photos/{filename}
Description: Serves individual photo files as static content.
Parameters:
filename
(path): The name of the photo fileResponse: Binary image data
Status Codes:
200
: Success - returns image file404
: Photo not foundEndpoint: POST /photos
Description: Saves a base64-encoded photo locally and uploads it to Immich cloud storage with album assignment.
Request Headers:
Content-Type: application/json
Request Body:
{
"photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}
Request Fields:
photo
(string, required): Base64-encoded image data with data URI prefixResponse:
{
"message": "Photo saved: photo-1640995200000.png",
"path": "./photos/photo-1640995200000.png"
}
Workflow:
photos/
directoryStatus Codes:
200
: Success - photo saved and uploaded400
: Bad request - no photo data provided500
: Server error - failed to save or upload photoEndpoint: DELETE /photos/{filename}
Description: Deletes a photo from local storage.
Parameters:
filename
(path): The name of the photo file to deleteResponse:
{
"message": "Photo deleted"
}
Status Codes:
200
: Success - photo deleted500
: Server error - failed to delete photoNote: This endpoint only deletes from local storage, not from Immich cloud storage.
Endpoint: GET /album-url
Description: Retrieves the Immich album URL for QR code generation.
Request: No body required
Response:
{
"album_url": "https://photos.example.com/albums/album-uuid-here"
}
Status Codes:
200
: Success - returns album URL503
: Service unavailable - Immich configuration incompleteNote: The album URL is constructed from the IMMICH_BASE_URL
and IMMICH_ALBUM_ID
environment variables.
Photos are automatically named using the pattern: photo-{timestamp}.png
timestamp
: Unix timestamp in millisecondsImages should be provided as data URIs with the following format:
data:image/{type};base64,{base64-encoded-data}
Supported image types:
The application automatically performs the following Immich operations when saving photos:
POST {IMMICH_BASE_URL}/assets
assetData
: Binary image filedeviceAssetId
: Unique identifier (filename + modification time)deviceId
: Static identifier ("nodejs"
)fileCreatedAt
: ISO timestampfileModifiedAt
: ISO timestampisFavorite
: Boolean ("false"
)PUT {IMMICH_BASE_URL}/albums/{IMMICH_ALBUM_ID}/assets
All endpoints return JSON error responses in the following format:
{
"error": "Error description"
}
Common error scenarios:
The application requires:
curl -X POST http://localhost:3000/photos \
-H "Content-Type: application/json" \
-d '{"photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."}'
curl http://localhost:3000/photos
curl -X DELETE http://localhost:3000/photos/photo-1640995200000.png
http://localhost:3000/photos/photo-1640995200000.png