Immich API Client

Unofficial Python client for the Immich API.

Important

This repository is mostly auto-generated from the Immich OpenAPI specification. Pull requests are welcome, but modifications to auto-generated code will be rejected. See CONTRIBUTING for more details.

Note

This project is auto-synced with the latest Immich release.

Note

This project is not affiliated with or endorsed by Immich.

Versioning

This package follows Semantic Versioning. Some important notes:

• Package version is not the server version: immich package x.y.z is the client’s own version.
• Upstream breaking changes ⇒ major bump: Breaking Immich changes produce a new major version of this package.
• Supported Immich server version: IMMICH-VERSION tracks the Immich version the client was generated from. To find a compatible package version for your server's version, see COMPATIBILITY.csv.

Installation

You need Python 3.10–3.14 installed to be able to use this library.

Install the latest stable version from PyPI:

pip install immich

If you want the latest version (which may be a pre-release):

pip install --pre immich

Structure

This SDK is async-only. The client exposes API groups as attributes, and endpoints as methods on those groups. Groups and endpoints are documented in the Immich API documentation.

Custom functions

Some API groups include custom convenience methods that are preferred over the auto-generated ones for common operations:

Assets API

• assets.download_asset_to_file: Download an asset (original file) directly to disk.
• assets.view_asset_to_file: Download an asset thumbnail directly to disk .
• assets.play_asset_video_to_file: Download an asset video stream directly to disk.
• assets.upload: Upload assets with smart features (duplicate detection, album management, sidecar support, dry run).

Resumable Downloads: All asset download methods support automatic resumable downloads.

Download API

• download.download_archive_to_file: Download asset archives (ZIP files) directly to disk. You can download whole albums or user-specified assets in a single request.

Note: Archive downloads (ZIP files) do not support resumable downloads due to the nature of streaming archives.

Users API

• users.get_profile_image_to_file: Download a user's profile image directly to disk.

Authentication

Immich supports API keys. Create one in your server and pass it via api_key=.... Cookie and Bearer tokens are also supported.

Usage

With a context manager (recommended):

from immich import AsyncClient

async with AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api") as client:
    await client.server.get_about_info()

Without a context manager:

import asyncio
from immich import AsyncClient

async def main():
    client = AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api")
    try:
        await client.server.get_about_info()
    finally:
        await client.close()

asyncio.run(main())

Response Types

There are three different available output formats you can choose from:

Serialized Response

You can get fully serialized responses as Pydantic models. Using this, you get the full benefits of Pydantic's type checking.

res = await client.server.get_about_info()

The output would look like this:

ServerAboutResponseDto(...)

Serialized Response with HTTP Info

res = await client.server.get_about_info_with_http_info()

The output would look like this:

status_code=200 headers={'Content-Type': 'application/json'} data=ServerAboutResponseDto(...) raw_data=b'{"...": "..."}'

JSON Response

You can receive a classical JSON response by suffixing the function name with _without_preload_content:

response = await client.server.get_about_info_without_preload_content()
await response.json()

Session management

The client can manage a shared aiohttp.ClientSession, or you can pass your own via http_client=... (you are responsible for its lifecycle).