immich-sdk

A modern Rust SDK for the Immich photo and video management server.

Features

• Async-first: Built on tokio and reqwest for modern async Rust
• Builder pattern: Ergonomic API with fluent builders
• Type-safe: Strongly typed models
• Error handling: Comprehensive error types with thiserror
• Rustls TLS: Uses rustls instead of OpenSSL

Installation

Add this to your Cargo.toml:

[dependencies]
immich-sdk = "1.137"

Quick Start

use immich_sdk::{Client, error::Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client
    let client = Client::from_url("https://immich.example.com")?
        .with_api_key("your-api-key");

    // List albums
    let albums = client.albums().list().execute().await?;
    println!("Found {} albums", albums.len());

    // Upload an asset
    let asset = client
        .assets()
        .upload()
        .file("/path/to/photo.jpg")
        .device_asset_id("phone-123")
        .device_id("my-device")
        .execute()
        .await?;

    println!("Uploaded asset: {:?}", asset.id);

    Ok(())
}

Authentication

The SDK supports API key authentication:

use immich_sdk::Client;

let client = Client::from_url("https://immich.example.com")?
    .with_api_key("your-api-key-here");

API Modules

Assets

Upload, download, and manage photos and videos:

// List all assets
let assets = client.assets().list().execute().await?;

// Get a specific asset
let asset = client.assets().get(asset_id).execute().await?;

// Upload a new asset
let uploaded = client
    .assets()
    .upload()
    .file("/path/to/photo.jpg")
    .device_asset_id("unique-device-id")
    .device_id("device-name")
    .favorite()
    .execute()
    .await?;

// Delete assets
client
    .assets()
    .delete()
    .id(asset_id)
    .execute()
    .await?;

Albums

Create and manage albums:

// Create an album
let album = client
    .albums()
    .create()
    .name("My Vacation")
    .execute()
    .await?;

// Add assets to album
client
    .albums()
    .add_assets(album.id)
    .asset_ids(vec![asset_id1, asset_id2])
    .execute()
    .await?;

// List all albums
let albums = client.albums().list().execute().await?;

Server Info

Get server information:

// Get server version
let version = client.server().version().await?;
println!("Server version: {}", version);

// Get server features
let features = client.server().features().await?;
println!("OAuth enabled: {}", features.oauth);

// Ping the server
let pong = client.server().ping().await?;
println!("Ping: {}", pong);

Error Handling

The SDK uses the ImmichError type for all errors:

use immich_sdk::error::ImmichError;

match client.assets().get(asset_id).execute().await {
    Ok(asset) => println!("Found: {:?}", asset),
    Err(ImmichError::NotFound(_)) => println!("Asset not found"),
    Err(ImmichError::Authentication(_)) => println!("Auth failed"),
    Err(e) => println!("Error: {}", e),
}

Configuration

Create a client with custom configuration:

use immich_sdk::{Client, Config};
use std::time::Duration;

let config = Config::new("https://immich.example.com")
    .with_api_key("your-api-key")
    .with_timeout(Duration::from_secs(60));

let client = Client::new(config)?;

License

This project is licensed under the MIT OR Apache-2.0 license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Immich - The amazing photo and video management solution