curl --request POST \
--url https://api.example.com/api/assets \
--header 'Content-Type: multipart/form-data' \
--form asset_data='@example-file' \
--form 'device_asset_id=<string>' \
--form 'device_id=<string>' \
--form file_created_at=2023-11-07T05:31:56Z \
--form file_modified_at=2023-11-07T05:31:56Z \
--form 'library_id=<string>'{
"id": "<string>",
"device_asset_id": "<string>",
"device_id": "<string>",
"mime_type": "<string>",
"original_file_name": "<string>",
"file_created_at": "2023-11-07T05:31:56Z",
"file_modified_at": "2023-11-07T05:31:56Z",
"local_datetime": "2023-11-07T05:31:56Z",
"checksum": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"checksum_sha1": "<string>",
"metadata": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 123,
"modified_datetime": "2023-11-07T05:31:56Z",
"original_datetime": "2023-11-07T05:31:56Z",
"digitized_datetime": "2023-11-07T05:31:56Z",
"lens_model": "<string>",
"f_number": 123,
"focal_length": 123,
"iso": 123,
"exposure_time": 123,
"exposure_bias": 123,
"latitude": 123,
"longitude": 123,
"altitude": 123,
"city": "<string>",
"state": "<string>",
"country": "<string>",
"country_code": "<string>",
"sublocation": "<string>",
"place_name": "<string>",
"timezone": "<string>",
"display_label": "<string>",
"description": "<string>",
"fps": 123,
"live_photo_cid": "<string>",
"projection_type": "<string>",
"auto_stack_id": "<string>",
"rating": 123
},
"metrics": {},
"asset_urls": {},
"description": "<string>",
"faces": [
{
"id": "<string>",
"asset_id": "<string>",
"bounding_box": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"person_id": "<string>",
"timestamp_ms": 123,
"asset_urls": {},
"cluster_assignment": {
"distance_to_person": 123,
"candidates": [
{
"person_id": "<string>",
"distance": 123,
"name": "<string>"
}
]
}
}
],
"people": [
{
"id": "<string>",
"is_hidden": true,
"is_favorite": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"birth_date": "2023-12-25",
"asset_count": 123,
"thumbnail_face_id": "<string>",
"asset_urls": {},
"cluster_metrics": {
"pairwise_p90": 123,
"pairwise_mean": 123,
"face_count": 123
}
}
],
"width": 0,
"height": 0,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}Uploads a new asset file (image or video) along with its metadata to the specified library. If no library_id is provided and the user only has one library, uses that library. If the user has multiple libraries, library_id is required.
curl --request POST \
--url https://api.example.com/api/assets \
--header 'Content-Type: multipart/form-data' \
--form asset_data='@example-file' \
--form 'device_asset_id=<string>' \
--form 'device_id=<string>' \
--form file_created_at=2023-11-07T05:31:56Z \
--form file_modified_at=2023-11-07T05:31:56Z \
--form 'library_id=<string>'{
"id": "<string>",
"device_asset_id": "<string>",
"device_id": "<string>",
"mime_type": "<string>",
"original_file_name": "<string>",
"file_created_at": "2023-11-07T05:31:56Z",
"file_modified_at": "2023-11-07T05:31:56Z",
"local_datetime": "2023-11-07T05:31:56Z",
"checksum": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"checksum_sha1": "<string>",
"metadata": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 123,
"modified_datetime": "2023-11-07T05:31:56Z",
"original_datetime": "2023-11-07T05:31:56Z",
"digitized_datetime": "2023-11-07T05:31:56Z",
"lens_model": "<string>",
"f_number": 123,
"focal_length": 123,
"iso": 123,
"exposure_time": 123,
"exposure_bias": 123,
"latitude": 123,
"longitude": 123,
"altitude": 123,
"city": "<string>",
"state": "<string>",
"country": "<string>",
"country_code": "<string>",
"sublocation": "<string>",
"place_name": "<string>",
"timezone": "<string>",
"display_label": "<string>",
"description": "<string>",
"fps": 123,
"live_photo_cid": "<string>",
"projection_type": "<string>",
"auto_stack_id": "<string>",
"rating": 123
},
"metrics": {},
"asset_urls": {},
"description": "<string>",
"faces": [
{
"id": "<string>",
"asset_id": "<string>",
"bounding_box": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"person_id": "<string>",
"timestamp_ms": 123,
"asset_urls": {},
"cluster_assignment": {
"distance_to_person": 123,
"candidates": [
{
"person_id": "<string>",
"distance": 123,
"name": "<string>"
}
]
}
}
],
"people": [
{
"id": "<string>",
"is_hidden": true,
"is_favorite": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"birth_date": "2023-12-25",
"asset_count": 123,
"thumbnail_face_id": "<string>",
"asset_urls": {},
"cluster_metrics": {
"pairwise_p90": 123,
"pairwise_mean": 123,
"face_count": 123
}
}
],
"width": 0,
"height": 0,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}Documentation Index
Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
Use this file to discover all available pages before exploring further.
Successful Response
Represents a photo or video asset with metadata and access URLs.
Unique asset identifier with 'asset_' prefix
Original asset identifier from the device that uploaded this asset
Identifier of the device that uploaded this asset
MIME type of the file (e.g., 'image/jpeg', 'video/mp4')
Original filename when the asset was uploaded
When the file was created on the uploading device
When the file was last modified on the uploading device
When the photo/video was taken, in the device's local timezone
Base64-encoded SHA-256 hash of the asset contents for duplicate detection and integrity
When this asset record was created in the database
When this asset record was last updated
Base64-encoded SHA-1 hash for Immich client compatibility. May be null for older assets.
Asset metadata — camera/EXIF fields, GPS, and location names.
Show child attributes
ML-generated quality scores and other metrics
Show child attributes
Named asset variants: 'original', 'thumbnail', 'preview', 'fullsize' for images; 'original' only for videos
Show child attributes
AI-generated description of the asset's content, quality, and composition. null means description generation has not yet run; empty string means the model refused to describe the asset. Distinct from metadata.description (camera-embedded EXIF metadata).
All faces detected in this asset
Show child attributes
All unique people identified in this asset (deduplicated from faces)
Show child attributes
Width of the asset in pixels
Height of the asset in pixels
File size of the asset in bytes
When this asset was moved to trash (ISO 8601, UTC). null for live assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window.