360 Secure SkillHub
360 安全技能中心

Immich API Connector

提供 Immich REST API 的操作指引与批量上传、相册下载脚本，可通过环境变量或命令行参数配置实例地址与 API Key，覆盖相册、资源、用户、搜索、媒体库和任务接口，用于照片备份、整理与传输。

ninjazan420
ninjazan420
热度 74.58
最近更新 2026-05-17 12:02:42
分类：自动化依赖：代码执行 / 读写文件 / 第三方 API应用场景：API 集成 / 自动化脚本 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add immich-api
Metadata
name
immich-api
description
Immich Photo Management API Bridge. Use for interacting with self-hosted Immich instances via REST API. Triggers when: (1) User wants to manage photos, albums, or assets in Immich, (2) Building automation around photo backups, (3) Searching or organizing media, (4) User management in Immich, (5) Upload/download photos via API, (6) Getting album or library information, (7) Working with Immich jobs/queues, (8) Any Immich-related photo tasks

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 photos
  • download_album.py - Download entire album
  • sync_library.py - Sync external library

See references/api-endpoints.md for complete endpoint reference.