181 lines
3.6 KiB
Markdown
181 lines
3.6 KiB
Markdown
# immich-sdk
|
|
|
|
A modern Rust SDK for the [Immich](https://immich.app/) 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`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
immich-sdk = "1.137"
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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](https://immich.app/) - The amazing photo and video management solution
|