immich-api

What This Skill Does

The immich-api skill acts as a robust bridge between the OpenClaw AI agent and your self-hosted Immich photo management server. It allows users to programmatically interact with their media library, enabling automated operations such as bulk photo uploads, album management, library scanning, and user administration. By abstracting the complexity of the Immich REST API, this skill allows the agent to handle sophisticated media organization tasks, search queries, and job queue monitoring directly through natural language requests. Whether you are automating a backup workflow or simply need to organize your digital memories, this skill serves as the primary interface for your Immich instance.

Installation

To integrate this skill into your OpenClaw environment, execute the following command in your terminal: clawhub install openclaw/skills/skills/ninjazan420/immich-api

Once installed, you must configure your instance credentials. This can be done by setting environment variables IMMICH_URL and IMMICH_API_KEY in your shell (PowerShell or Bash) or by passing them as arguments via provided scripts. You can generate an API key by navigating to your Immich web interface under User Profile -> API Keys.

Use Cases

1. Automated Backups: Trigger periodic synchronization of local folders to your Immich library.
2. Smart Media Organization: Use AI to search for specific content (e.g., "vacation at the beach") and automatically group those assets into a new album.
3. Administrative Tasks: Monitor server health by checking job statuses, triggering thumbnail generation, or managing library scans without manual intervention.
4. Media Retrieval: Quickly download specific high-resolution originals or thumbnails for external processing or viewing.

Example Prompts

1. "Find all photos of my cat from last year and move them into a new album called 'Cats 2023'."
2. "Upload all images from my '/home/user/imports/photos' directory to my library and trigger a metadata sync."
3. "Check the status of my thumbnail generation job and tell me how many assets are currently waiting in the queue."

Tips & Limitations

• Authentication: Always store your API keys securely; do not commit them to version control systems. Use environment variables for safety.
• Performance: Bulk operations, especially large file uploads, may experience latency depending on your server's hardware and network bandwidth.
• Scope: This skill strictly handles API interactions; ensure your Immich server is accessible over the network to the machine running OpenClaw.
• Rate Limiting: Be mindful of API rate limits if triggering mass operations, as excessive requests may cause your Immich instance to become temporarily unresponsive.