PhotoPrism Pet

AI-powered photo management and organization using PhotoPrism's REST API. Browse photos, search by people/faces, manage albums, and organize your photo library with face recognition and AI-powered categorization.

Features

• Photo Management: Browse, search, and organize photos
• Face Recognition: Detect and label faces, search by people
• Albums: Create, manage, and share photo albums
• Labels & Categories: AI-powered auto-categorization
• Subjects (People): Manage and search by recognized people
• Folders: Browse original folder structure
• Search: Advanced filtering by date, location, camera, labels, and more

Quick Start

1. Get Your PhotoPrism API Token

Option A: From Web UI

1. Open PhotoPrism (e.g., http://localhost:2342)
2. Go to Settings > Account
3. Scroll to Apps and Integrations
4. Click Show next to Access Token or generate a new one
5. Copy the token

Option B: From Settings File If you have access to PhotoPrism's storage:

# Look for the token in your PhotoPrism config
cat ~/.photoprism/storage/config/settings.yml | grep DownloadToken

2. Configure Environment

Create a .env file in your project root:

# Required: Your PhotoPrism API access token
PHOTOPRISM_API_TOKEN=your_token_here

# Optional: Base URL (defaults to http://localhost:2342)
# For remote instances, set the full URL:
# PHOTOPRISM_BASE_URL=https://photos.yourdomain.com

3. Test Connection

opencode run "test photoprism connection" --print-logs

Expected response:

{
  "success": true,
  "status": "connected",
  "message": "PhotoPrism connected successfully",
  "details": {
    "baseUrl": "http://localhost:2342",
    "configured": true,
    "config": {...},
    "count": {
      "photos": 1434,
      "albums": 5,
      "faces": 17,
      "labels": 89
    }
  }
}

Generated Tools (114 total)

This pet uses OpenAPI generation to automatically create tools from PhotoPrism's API specification.

Core Photo Tools (Read-Only)

• photoprism-search-photos - Search photos with filters (label, person, date, etc.)
• photoprism-get-photo - Get photo details by UID
• photoprism-get-photo-download - Download photo file
• photoprism-get-photo-yaml - Get photo metadata in YAML

Face & People Tools

• photoprism-search-faces - List all face clusters
• photoprism-get-face - Get face cluster details
• photoprism-update-face - Assign name/subject to face cluster
• photoprism-search-subjects - List all recognized people
• photoprism-get-subject - Get person details
• photoprism-update-subject - Update person information

Album Tools

• photoprism-search-albums - List all albums
• photoprism-get-album - Get album details
• photoprism-create-album - Create new album
• photoprism-update-album - Update album metadata
• photoprism-add-photos-to-album - Add photos to album
• photoprism-download-album - Download entire album

Label & Category Tools

• photoprism-search-labels - List all labels/categories
• photoprism-update-label - Update label metadata
• photoprism-like-label / photoprism-dislike-label - Mark favorite labels

Folder & Organization Tools

• photoprism-search-folders-originals - Browse original folders
• photoprism-search-folders-import - Browse import folders
• photoprism-search-geo - Search by location/GPS coordinates

Write Operations

• photoprism-start-indexing - Index new photos
• photoprism-start-import - Import photos from folder
• photoprism-approve-photo - Approve photo for public view
• photoprism-update-photo - Update photo metadata
• photoprism-add-photo-label - Add custom label to photo

Example Queries

Browse & Search Photos

# List all photos
opencode run "list all photos"

# Search by label
opencode run "search for photos labeled portrait"

# Search by date
opencode run "show me photos from June 2024"

# Search by camera
opencode run "find photos taken with Canon EOS 5D"

Face Recognition Workflow

# List all detected face clusters
opencode run "show me all face clusters"

# Get face cluster with most samples (likely bride or groom)
opencode run "get details for face cluster DMB3X34Z"

# Search photos with specific person
opencode run "find all photos of the bride"

# Find photos with unrecognized faces
opencode run "show photos with unknown faces"

Album Management

# List all albums
opencode run "list all albums"

# Create new album
opencode run "create an album called Wedding Highlights"

# Add photos to album
opencode run "add photo xyz123 to album abc456"

# Download album
opencode run "download album Wedding Highlights"

Organization & Labels

# Browse by category
opencode run "show me all photos labeled ceremony"

# Add custom label
opencode run "add label First Dance to photo xyz123"

# Browse by folder
opencode run "list photos in the ceremony folder"

Advanced Usage

Working with Face Clusters

PhotoPrism automatically creates face clusters during indexing. Here's a typical workflow:

1. Index photos with face detection:

opencode run "start indexing with face detection"

2. List face clusters:

opencode run "list all face clusters sorted by frequency"

3. Assign names to faces:

# The API will show you the cluster UID (e.g., "DMB3X34Z")
opencode run "assign name 'Bride' to face cluster DMB3X34Z"

4. Search photos by person:

opencode run "find all photos of the bride"

Smart Albums with Search Filters

Create dynamic albums that automatically include matching photos:

# Create album for portrait shots of specific people
opencode run "create smart album with filter: label:portrait person:Bride person:Groom"

# Create album for ceremony photos
opencode run "create album with filter: label:ceremony month:June"

# Create favorites album
opencode run "create album with filter: f:favorites"

Batch Operations (Advanced)

For bulk operations, use the batch endpoints:

# Approve multiple photos
opencode run "approve photos with UIDs: abc123, def456, ghi789"

# Archive multiple photos
opencode run "archive photos from folder tmp"

Configuration Options

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PHOTOPRISM_API_TOKEN | Yes | - | API access token from Settings > Account | | PHOTOPRISM_BASE_URL | No | http://localhost:2342 | Base URL for PhotoPrism instance |

Remote PhotoPrism Instance

To use with a remote PhotoPrism instance:

# .env
PHOTOPRISM_API_TOKEN=your_token_here
PHOTOPRISM_BASE_URL=https://photos.yourdomain.com

Regenerating OpenAPI Tools

When PhotoPrism updates its API, regenerate the tools:

cd pets/photoprism

# Download latest OpenAPI spec
curl -o openapi-spec.json https://raw.githubusercontent.com/photoprism/photoprism/develop/internal/api/swagger.json

# Regenerate tools
pets generate-openapi --verbose

# Test
opencode run "test photoprism connection"

API Documentation

PhotoPrism API documentation:

• REST API Docs: https://docs.photoprism.dev/
• OpenAPI Spec: https://github.com/photoprism/photoprism/blob/develop/internal/api/swagger.json
• Web UI: http://localhost:2342 (when running)

Troubleshooting

"Failed to connect: HTTP 401"

Cause: Invalid or missing API token

Solution:

1. Verify token in PhotoPrism Settings > Account
2. Check .env file has correct PHOTOPRISM_API_TOKEN
3. Restart your opencode session to reload environment variables

"Failed to connect: Connection refused"

Cause: PhotoPrism is not running or wrong URL

Solution:

1. Start PhotoPrism: docker-compose up -d photoprism
2. Verify it's running: curl http://localhost:2342/api/v1/status
3. Check PHOTOPRISM_BASE_URL matches your instance

No face clusters found

Cause: Face detection not enabled or not yet indexed

Solution:

1. Enable face recognition in PhotoPrism Settings > Library
2. Re-index with face detection: opencode run "start indexing"
3. Wait for indexing to complete (check status in web UI)

"Unknown faces" - How to assign names?

Use the update-face tool to assign subjects to face clusters:

# First, get face cluster UID from search-faces
opencode run "list face clusters"

# Then assign name to cluster
opencode run "update face cluster DMB3X34Z with subject UID of person John"

Or use the PhotoPrism web UI: People > click cluster > Add Name

Examples

Wedding Photo Organization Workflow

Based on the usage guide, here's a complete workflow:

# 1. Check indexing status
opencode run "test photoprism connection"

# 2. View detected face clusters
opencode run "list all face clusters sorted by sample count"

# 3. Label top people (bride, groom, parents, wedding party)
opencode run "list face cluster DMB3X34Z samples"  # 568 samples - likely bride
opencode run "assign name 'Bride' to face cluster DMB3X34Z"

# 4. Create albums by event
opencode run "create album 'Ceremony'"
opencode run "add photos from folder 'ceremony' to album 'Ceremony'"

# 5. Search and organize
opencode run "find all portrait photos of the bride"
opencode run "create smart album 'Best Shots' with filter: f:favorites"

# 6. Share albums
opencode run "create shareable link for album 'Ceremony'"

Related Pets

• @openpets/immich - Alternative photo management (Immich)
• @openpets/google-photos - Google Photos integration
• @openpets/flickr - Flickr photo hosting

License

This pet is part of the OpenPets ecosystem and follows the same license as the main repository.

Contributing

To contribute improvements:

1. Update the OpenAPI spec if PhotoPrism API changes
2. Regenerate tools: pets generate-openapi
3. Test thoroughly with various PhotoPrism versions
4. Submit PR with updated tools and documentation