Photos
Overview
Interface for Synology Photos API.
Provides methods to interact with Photos features such as retrieving user info, folders, albums, sharing, and items.
Parameters
ip_address str
The IP address or hostname of the Synology NAS.
port str
The port number to connect to.
username str
The username for authentication.
password str
The password for authentication.
secure bool
Whether to use HTTPS. Default is False.
cert_verify bool
Whether to verify SSL certificates. Default is False.
dsm_version int
DSM version. Default is 7.
debug bool
Enable debug output. Default is True.
otp_code str
One-time password for 2FA, if required.
device_id str
Device ID for the session.
device_name str
Device name for the session.
quickconnect_id str
QuickConnect ID for relay-based access. Defaults to None.
Methods
get_userinfo
Retrieve user information for the current session.
Internal API
SYNO.Foto.UserInfo
Returns
Any
The user information data.
get_folder
Retrieve information about a specific folder.
Internal API
SYNO.Foto.Browse.Folder
Parameters
folder_id int
The ID of the folder. Default is 0.
Returns
dict[str, object] or str
The folder information or an error message.
list_folders
List folders in Personal Space.
Internal API
SYNO.Foto.Browse.Folder
Parameters
folder_id int
The parent folder ID. Default is 0.
limit int
Maximum number of folders to return. Default is 1000.
offset int
Number of folders to skip. Default is 0.
additional str or list of str
Additional fields to include.
Returns
dict[str, object] or str
The list of folders or an error message.
list_teams_folders
List folders in Team Space.
Internal API
SYNO.FotoTeam.Browse.Folder
Parameters
folder_id int
The parent folder ID. Default is 0.
limit int
Maximum number of folders to return. Default is 2000.
offset int
Number of folders to skip. Default is 0.
additional str or list of str
Additional fields to include.
Returns
dict[str, object] or str
The list of team folders or an error message.
count_folders
Count folders in Personal Space.
Internal API
SYNO.Foto.Browse.Folder
Parameters
folder_id int
The parent folder ID. Default is 0.
Returns
dict[str, object] or str
The count of folders or an error message.
count_team_folders
Count folders in Team Space.
Internal API
SYNO.FotoTeam.Browse.Folder
Parameters
folder_id int
The parent folder ID. Default is 0.
Returns
dict[str, object] or str
The count of team folders or an error message.
lookup_folder
Lookup a folder by path in Personal Space.
Parameters
path str
The folder path.
Returns
dict[str, object] or str
The folder information or None if not found.
lookup_team_folder
Lookup a folder by path in Team Space.
Parameters
path str
The folder path.
Returns
dict[str, object] or str
The folder information or None if not found.
get_album
Retrieve information about a specific album.
Internal API
SYNO.Foto.Browse.Album
Parameters
album_id str
The album ID.
additional str or list of str
Additional fields to include.
Returns
dict[str, object] or str
The album information or an error message.
list_albums
List albums.
Internal API
SYNO.Foto.Browse.Album
Parameters
offset int
Number of albums to skip. Default is 0.
limit int
Maximum number of albums to return. Default is 100.
Returns
dict[str, object] or str
The list of albums or an error message.
suggest_condition
Suggest album conditions based on a keyword.
Internal API
SYNO.Foto.Browse.ConditionAlbum
Parameters
keyword str
The keyword to suggest conditions for.
condition list of str
List of conditions to use. Default is ['general_tag'].
user_id str
User ID to use. If None, uses the current user.
Returns
dict[str, object] or str
The suggested conditions or an error message.
create_album
Create a new album with the specified condition.
Internal API
SYNO.Foto.Browse.ConditionAlbum
Parameters
name str
The name of the album.
condition list of str
The condition for the album.
Returns
dict[str, object] or str
The API response for album creation.
delete_album
Delete an album by ID.
Internal API
SYNO.Foto.Browse.Album
Parameters
album_id str or int or list of str or int
The album ID or list of album IDs.
Returns
dict[str, object] or str
The API response for album deletion.
create_normal_album
Create a normal (manual) album with the specified items.
Internal API
SYNO.Foto.Browse.NormalAlbum
Parameters
name str
The name of the album.
item_ids list of int
List of item IDs to add to the album.
Returns
dict[str, object] or str
The API response. Album data is in data['album'].
rename_album
Rename an album.
Internal API
SYNO.Foto.Browse.Album
Parameters
album_id int
The ID of the album to rename.
name str
The new name for the album.
Returns
dict[str, object] or str
The API response.
get_normal_album
Retrieve information about a normal (manual) album.
Internal API
SYNO.Foto.Browse.NormalAlbum
Parameters
album_id int
The album ID.
Returns
dict[str, object] or str
The album information or an error message.
list_categories
List photo categories (recently added, geocoding, general tag, video).
Internal API
SYNO.Foto.Browse.Category
Returns
dict[str, object] or str
The list of categories or an error message.
list_concepts
List AI-detected concepts (tags, objects, scenes).
Internal API
SYNO.Foto.Browse.Concept
Parameters
offset int
Number of concepts to skip. Default is 0.
limit int
Maximum number of concepts to return. Default is 1000.
Returns
dict[str, object] or str
The list of concepts or an error message.
list_team_concepts
List AI-detected concepts in Team Space.
Parameters
offset int
Number of concepts to skip. Default is 0.
limit int
Maximum number of concepts to return. Default is 1000.
Returns
dict[str, object] or str
The list of concepts or an error message.
count_concepts
Count AI-detected concepts.
Returns
dict[str, object] or str
The count of concepts or an error message.
count_team_concepts
Count AI-detected concepts in Team Space.
Returns
dict[str, object] or str
The count of concepts or an error message.
list_general_tags
List general tags.
Internal API
SYNO.Foto.Browse.GeneralTag
Parameters
offset int
Number of tags to skip. Default is 0.
limit int
Maximum number of tags to return. Default is 1000.
Returns
dict[str, object] or str
The list of tags or an error message.
list_team_general_tags
List general tags in Team Space.
Parameters
offset int
Number of tags to skip. Default is 0.
limit int
Maximum number of tags to return. Default is 1000.
Returns
dict[str, object] or str
The list of tags or an error message.
count_general_tags
Count general tags.
Returns
dict[str, object] or str
The count of tags or an error message.
count_team_general_tags
Count general tags in Team Space.
Returns
dict[str, object] or str
The count of tags or an error message.
list_geocoding
List geocoding locations from all photos.
Internal API
SYNO.Foto.Browse.Geocoding
Parameters
offset int
Number of locations to skip. Default is 0.
limit int
Maximum number of locations to return. Default is 1000.
Returns
dict[str, object] or str
The list of geocoding locations or an error message.
list_team_geocoding
List geocoding locations in Team Space.
Parameters
offset int
Number of locations to skip. Default is 0.
limit int
Maximum number of locations to return. Default is 1000.
Returns
dict[str, object] or str
The list of geocoding locations or an error message.
count_geocoding
Count geocoding locations.
Returns
dict[str, object] or str
The count of geocoding locations or an error message.
count_team_geocoding
Count geocoding locations in Team Space.
Returns
dict[str, object] or str
The count of geocoding locations or an error message.
list_persons
List detected persons (face recognition).
Internal API
SYNO.Foto.Browse.Person
Parameters
offset int
Number of persons to skip. Default is 0.
limit int
Maximum number of persons to return. Default is 1000.
Returns
dict[str, object] or str
The list of persons or an error message.
list_team_persons
List detected persons in Team Space.
Parameters
offset int
Number of persons to skip. Default is 0.
limit int
Maximum number of persons to return. Default is 1000.
Returns
dict[str, object] or str
The list of persons or an error message.
count_persons
Count detected persons.
Returns
dict[str, object] or str
The count of persons or an error message.
count_team_persons
Count detected persons in Team Space.
Returns
dict[str, object] or str
The count of persons or an error message.
get_person
Get information about a detected person.
Internal API
SYNO.Foto.Browse.Person
Parameters
person_id int
The person ID (from list_persons()).
Returns
dict[str, object] or str
The person information or an error message.
rename_person
Rename a detected person.
Internal API
SYNO.Foto.Browse.Person
Parameters
person_id int
The person ID (from list_persons()).
name str
The new name for the person. Use 'Unnamed' to clear.
Returns
dict[str, object] or str
The API response.
list_items_by_person
List photos of a specific person.
Internal API
SYNO.Foto.Browse.Item
Parameters
person_id int
The person ID (from list_persons()).
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
additional list of str
Additional fields to include (e.g., ['thumbnail', 'person']).
Returns
dict[str, object] or str
The list of photos or an error message.
get_team_person
Get information about a detected person in Team Space.
Internal API
SYNO.FotoTeam.Browse.Person
Parameters
person_id int
The person ID (from list_team_persons()).
Returns
dict[str, object] or str
The person information or an error message.
list_items_by_team_person
List Team Space photos of a specific person.
Internal API
SYNO.FotoTeam.Browse.Item
Parameters
person_id int
The person ID (from list_team_persons()).
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
additional list of str
Additional fields to include.
Returns
dict[str, object] or str
The list of photos or an error message.
list_recently_added
List recently added items.
Internal API
SYNO.Foto.Browse.RecentlyAdded
Parameters
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
Returns
dict[str, object] or str
The list of recently added items or an error message.
list_team_recently_added
List recently added items in Team Space.
Parameters
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
Returns
dict[str, object] or str
The list of recently added items or an error message.
count_recently_added
Count recently added items.
Returns
dict[str, object] or str
The count of recently added items or an error message.
count_team_recently_added
Count recently added items in Team Space.
Returns
dict[str, object] or str
The count of recently added items or an error message.
get_timeline
Get the timeline sections.
Internal API
SYNO.Foto.Browse.Timeline
Returns
dict[str, object] or str
The timeline sections or an error message.
get_team_timeline
Get the Team Space timeline sections.
Internal API
SYNO.FotoTeam.Browse.Timeline
Returns
dict[str, object] or str
The timeline sections or an error message.
get_similar_timeline
Get the similar-items timeline.
Internal API
SYNO.Foto.Browse.SimilarTimeline
Returns
dict[str, object] or str
The similar timeline sections or an error message.
get_team_similar_timeline
Get the Team Space similar-items timeline.
Internal API
SYNO.FotoTeam.Browse.SimilarTimeline
Returns
dict[str, object] or str
The similar timeline sections or an error message.
list_similar_items
List items similar to the specified item.
Internal API
SYNO.Foto.Browse.SimilarItem
Parameters
item_id int
The ID of the reference item.
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
Returns
dict[str, object] or str
The list of similar items or an error message.
list_team_similar_items
List items similar to the specified item in Team Space.
Internal API
SYNO.FotoTeam.Browse.SimilarItem
Parameters
item_id int
The ID of the reference item.
offset int
Number of items to skip. Default is 0.
limit int
Maximum number of items to return. Default is 1000.
Returns
dict[str, object] or str
The list of similar items or an error message.
set_album_condition
Set the condition for an album.
Internal API
SYNO.Foto.Browse.ConditionAlbum
Parameters
folder_id int
The folder ID.
condition list of str
The condition to set.
Returns
dict[str, object] or str
The API response for setting the condition.
share_album
Share an album with specified permissions.
Internal API
SYNO.Foto.Sharing.Passphrase
Parameters
album_id str
The album ID.
permission str or list of str
Permissions to set.
enabled bool
Whether sharing is enabled. Default is True.
expiration int or str
Expiration time for the share. Default is 0.
Returns
Any
The API response for sharing the album.
share_team_folder
Share a team folder with specified permissions.
Internal API
SYNO.FotoTeam.Sharing.Passphrase
Parameters
folder_id int
The folder ID.
permission str
Permissions to set.
enabled bool
Whether sharing is enabled. Default is True.
expiration int or str
Expiration time for the share. Default is 0.
Returns
Any
The API response for sharing the team folder.
list_shareable_users_and_groups
List users and groups that can be shared with.
Internal API
SYNO.Foto.Sharing.Misc
Parameters
team_space_sharable_list bool
Whether to include team space sharable list. Default is False.
Returns
dict[str, object] or str
The list of users and groups or an error message.
list_item_in_folders
List items in a Personal Space folder.
Parameters
offset int
Specify how many items are skipped before beginning to return listed items.
limit int
Number of items requested. Default is 1000.
folder_id int, required
ID of the folder returned by list_folders.
sort_by str
Possible values: 'filename', 'filesize', 'takentime', 'item_type'.
sort_direction str
Possible values: 'asc' or 'desc'. Defaults to: 'desc'.
type str
Possible values: 'photo', 'video', 'live'.
passphrase str
Passphrase for a shared album.
additional list
Additional fields to include.
Possible values:
["thumbnail","resolution", "orientation", "video_convert", "video_meta", "provider_user_id", "exif", "tag", "description", "gps", "geocoding_id", "address", "person"].
Returns
dict[str, object] or str
The list of items or an error message.
list_item_in_team_folders
List items in a Team Space folder.
Parameters
offset int
Specify how many items are skipped before beginning to return listed items.
limit int
Number of items requested. Default is 1000.
folder_id int, required
ID of the folder returned by list_teams_folders.
sort_by str
Possible values: 'filename', 'filesize', 'takentime', 'item_type'.
sort_direction str
Possible values: 'asc' or 'desc'. Defaults to: 'desc'.
type str
Possible values: 'photo', 'video', 'live'.
passphrase str
Passphrase for a shared album.
additional list
Additional fields to include.
Possible values:
["thumbnail","resolution", "orientation", "video_convert", "video_meta", "provider_user_id", "exif", "tag", "description", "gps", "geocoding_id", "address", "person"].
Returns
dict[str, object] or str
The list of team items or an error message.
list_items_in_album
List items in an album.
Parameters
album_id int, required
The ID of the album (from list_albums()).
offset int
Specify how many items are skipped before beginning to return listed items.
limit int
Number of items requested. Default is 1000.
sort_by str
Possible values: 'filename', 'filesize', 'takentime', 'item_type'.
sort_direction str
Possible values: 'asc' or 'desc'. Defaults to 'desc'.
type str
Possible values: 'photo', 'video', 'live'.
passphrase str
Passphrase for a shared album.
additional list
Additional fields to include.
Possible values:
["thumbnail", "resolution", "orientation", "video_convert", "video_meta", "provider_user_id", "exif", "tag", "description", "gps", "geocoding_id", "address", "person"].
Returns
dict[str, object] or str
The list of album items or an error message.
count_items_in_album
Count items in an album.
Internal API
SYNO.Foto.Browse.Item
Parameters
album_id int
The ID of the album.
Returns
dict[str, object] or str
The count of album items or an error message.
list_items_in_team_album
List items in a Team Space album.
Parameters
album_id int, required
The ID of the Team Space album (from list_albums()).
offset int
Specify how many items are skipped before beginning to return listed items.
limit int
Number of items requested. Default is 1000.
sort_by str
Possible values: 'filename', 'filesize', 'takentime', 'item_type'.
sort_direction str
Possible values: 'asc' or 'desc'. Defaults to 'desc'.
type str
Possible values: 'photo', 'video', 'live'.
passphrase str
Passphrase for a shared album.
additional list
Additional fields to include.
Possible values:
["thumbnail", "resolution", "orientation", "video_convert", "video_meta", "provider_user_id", "exif", "tag", "description", "gps", "geocoding_id", "address", "person"].
Returns
dict[str, object] or str
The list of album items or an error message.
count_items_in_team_album
Count items in a Team Space album.
Internal API
SYNO.FotoTeam.Browse.Item
Parameters
album_id int
The ID of the Team Space album.
Returns
dict[str, object] or str
The count of album items or an error message.
list_search_filters
List available search filters.
Internal API
SYNO.Foto.Search.Filter
Returns
dict[str, object] or str
The list of search filters or an error message.
get_guest_settings
Retrieve guest settings for Photos.
Internal API
SYNO.Foto.Setting.Guest
Returns
dict[str, object] or str
The guest settings or an error message.
get_index_status
Get the indexing status for photos.
Internal API
SYNO.Foto.Index
Returns
dict[str, object] or str
The index status counters (basic, thumbnail, metadata, face, concept, geo)
or an error message.
get_team_index_status
Get the Team Space indexing status for photos.
Internal API
SYNO.FotoTeam.Index
Returns
dict[str, object] or str
The index status counters or an error message.
get_admin_settings
Get the admin settings for Photos.
Internal API
SYNO.Foto.Setting.Admin
Returns
dict[str, object] or str
The admin settings (package version, global config) or an error message.
set_admin_settings
Set admin settings for Photos.
Internal API
SYNO.Foto.Setting.Admin
Parameters
_kwargs_** dict
Admin settings key-value pairs to set.
Returns
dict[str, object] or str
The API response.
get_user_settings
Get the user settings for Photos.
Internal API
SYNO.Foto.Setting.User
Returns
dict[str, object] or str
The user settings (theme, sort, AME status) or an error message.
set_user_settings
Set user settings for Photos.
Internal API
SYNO.Foto.Setting.User
Parameters
_kwargs_** dict
User settings key-value pairs to set.
Returns
dict[str, object] or str
The API response.
get_team_space_settings
Get Team Space settings.
Internal API
SYNO.Foto.Setting.TeamSpace
Returns
dict[str, object] or str
The Team Space settings (enabled, concepts, person, similar) or an error message.
set_team_space_settings
Set Team Space settings.
Internal API
SYNO.Foto.Setting.TeamSpace
Parameters
_kwargs_** dict
Team Space settings key-value pairs to set.
Returns
dict[str, object] or str
The API response.
get_wizard_settings
Get the wizard (first-time setup) settings for Photos.
Internal API
SYNO.Foto.Setting.Wizard
Returns
dict[str, object] or str
The wizard settings or an error message.
set_wizard_settings
Set wizard (first-time setup) settings for Photos.
Internal API
SYNO.Foto.Setting.Wizard
Parameters
_kwargs_** dict
Wizard settings key-value pairs to set.
Returns
dict[str, object] or str
The API response.
get_mobile_compatibility
Get mobile version compatibility info.
Internal API
SYNO.Foto.Setting.MobileCompatibility
Returns
dict[str, object] or str
The mobile compatibility settings or an error message.
get_item_info
Get detailed information about a photo item.
Internal API
SYNO.Foto.Browse.Item
Parameters
item_id int
The item ID (from list_items_in_album() or list_item_in_folders()).
additional list of str
Additional fields to include.
Possible values:
["exif", "gps", "tag", "description", "person", "address", "thumbnail", "resolution", "orientation"].
Returns
dict[str, object] or str
The item information. Detail fields are in data['list'][0]['additional'].
set_item_description
Set the description of a photo item.
Internal API
SYNO.Foto.Browse.Item
Parameters
item_id int
The item ID.
description str
The new description. Pass an empty string to clear it.
Returns
dict[str, object] or str
The API response.
set_item_favorite
Set or unset the favorite flag on a photo item.
Internal API
SYNO.Foto.Browse.Item
Parameters
item_id int
The item ID.
favorite bool
True to mark as favorite, False to unmark. Default is True.
Returns
dict[str, object] or str
The API response.
set_item_rating
Set the star rating of a photo item (0-5).
Internal API
SYNO.Foto.Browse.Item
Parameters
item_id int
The item ID.
rating int
Star rating from 0 to 5. Default is 0.
Returns
dict[str, object] or str
The API response.
search_suggestions
Get search suggestions for a keyword.
Internal API
SYNO.Foto.Search.Search
Parameters
keyword str
The search keyword.
Returns
dict[str, object] or str
The search suggestions or an error message.
download_item
Download a photo item to a file.
Internal API
SYNO.Foto.Download
Parameters
item_id int
The item ID to download.
dest_path str
The destination file path. If not provided, saves to the current
directory using the item's filename.
Returns
str or None
The path to the downloaded file, or None if the download failed.
upload_personal
Upload a file to Synology Photos Personal Space.
Parameters
file_path str
Path to the local file to upload.
folder str or list of str
Target folder(s). Pass a string like "PhotoLibrary" or a
list like ["PhotoLibrary", "MyAlbum"].
Default is "PhotoLibrary".
duplicate str
How to handle duplicate filenames. "ignore" (skip),
"rename" (auto-rename), or "overwrite".
Default is "ignore".
upload_destination str or None
Where to place the photo. "timeline" (add to timeline),
"folder" (folder only), or None (default behaviour).
Default is None.
Returns
dict[str, object] or str
API response with action, id, and unit_id on success.
upload_team
Upload a file to Synology Photos Team Space.
Parameters
file_path str
Path to the local file to upload.
folder str or list of str
Target folder(s). Pass a string like "PhotoLibrary" or a
list like ["PhotoLibrary", "TeamAlbum"].
Default is "PhotoLibrary".
duplicate str
How to handle duplicate filenames. "ignore" (skip),
"rename" (auto-rename), or "overwrite".
Default is "ignore".
upload_destination str or None
Where to place the photo. "timeline" (add to timeline),
"folder" (folder only), or None (default behaviour).
Default is None.
Returns
dict[str, object] or str
API response with action, id, and unit_id on success.
get_thumbnail
Download a photo thumbnail.
Internal API
SYNO.Foto.Thumbnail
Parameters
item_id int
The photo unit ID.
size str
Thumbnail size: "sm" (small), "m" (medium),
"xl" (large). Default is "sm".
dest_path str or None
Where to save the thumbnail. If None, saves as
{item_id}_{size}.jpg in the current directory.
Returns
str or None
Path to the saved thumbnail, or None on failure.
count_units
Count all photo/video units in a folder.
Internal API
SYNO.Foto.Browse.Unit
Parameters
folder_id int
The folder ID. Default is 0 (root).
Returns
dict[str, object] or str
The count of units or an error message.
get_unit
Get a single photo/video unit by ID.
Internal API
SYNO.Foto.Browse.Unit
Parameters
unit_id int
The unit ID.
folder_id int
The folder ID containing the unit. Default is 0.
additional str or list of str
Extra fields to return (e.g. ["thumbnail"]).
Returns
dict[str, object] or str
The unit data or an error message.
get_thumbnail_status
Get thumbnail generation status queue.
Shows how many thumbnails are pending generation.
Internal API
SYNO.Foto.Browse.Unit
Parameters
folder_id int
The folder ID. Default is 0.
Returns
dict[str, object] or str
Thumbnail generation status or an error message.
get_diff
Get incremental changes since a given diff version.
Useful for keeping a local index in sync with the NAS
without re-scanning the entire library.
Internal API
SYNO.Foto.Browse.Diff
Parameters
diff_version int
Last known diff version. Pass 0 to get everything.
Default is 0.
limit int
Max items to return. Default is 200.
version_time int
Timestamp for diff versioning. Default is 0.
Returns
dict[str, object] or str
The diff data or an error message.
get_diff_version
Get the current diff version.
Store this value and pass it to get_diff() next time
to receive only changes since this point.
Internal API
SYNO.Foto.Browse.Diff
Returns
dict[str, object] or str
The current diff version or an error message.
merge_persons
Merge one or more persons into a target person.
All faces assigned to the source persons will be reassigned
to the target person.
Internal API
SYNO.Foto.Browse.Person
Parameters
source_person_ids list of int
Person IDs to merge from.
target_person_id int
Person ID to merge into.
Returns
dict[str, object] or str
API response with the result of the merge operation.
separate_person
Separate faces from a person into a new person.
Internal API
SYNO.Foto.Browse.Person
Parameters
person_id int
The person to separate faces from.
face_ids list of int
Face IDs to move to a new person.
Returns
dict[str, object] or str
API response with the newly created person info.
list_faces
List faces assigned to a person.
Internal API
SYNO.Foto.Browse.Person
Parameters
person_id int
The person ID.
offset int
Results offset. Default 0.
limit int
Max results. Default 100.
Returns
dict[str, object] or str
API response with list of face objects.
get_general_tag
Get a single general tag by ID.
Internal API
SYNO.Foto.Browse.GeneralTag
Parameters
tag_id int
The tag ID.
Returns
dict[str, object] or str
API response with the tag data.
create_general_tag
Create a new general tag.
Internal API
SYNO.Foto.Browse.GeneralTag
Parameters
name str
Tag name.
Returns
dict[str, object] or str
API response with the created tag data.
list_favorites
List favorite items in Personal Space.
.. note::
This API endpoint (SYNO.Foto.Favorite) may not be available
on all DSM versions. On DSM 7.3 it returns error 103
(method not found). Use list_items with appropriate filters
as a fallback.
Internal API
SYNO.Foto.Favorite
Parameters
offset int
Number of items to skip. Default is 0.
limit int
Max items to return. Default is 200.
Returns
dict[str, object] or str
API response with favorite items. May return error 103 on
DSM versions where SYNO.Foto.Favorite is unavailable.
get_shared_passphrase
Get passphrase info for a shared item.
Internal API
SYNO.Foto.Sharing.Passphrase
Parameters
shared_id str
The shared item ID.
Returns
dict[str, object] or str
API response with passphrase info.
get_shared_permission
Check permissions for a passphrase-protected share.
Internal API
SYNO.Foto.Sharing.Passphrase
Parameters
shared_id str
The shared item ID.
passphrase str
The passphrase to check.
Returns
dict[str, object] or str
API response with permission check result.
set_shared_passphrase
Set or update a passphrase on a shared item.
Internal API
SYNO.Foto.Sharing.Passphrase
Parameters
shared_id str
The shared item ID.
passphrase str
The passphrase. Empty string disables it.
enable_passphrase bool
Whether passphrase protection is active.
Default is True.
Returns
dict[str, object] or str
API response confirming the passphrase update.
list_background_tasks
List all user background tasks (indexing, thumbnail gen).
Internal API
SYNO.Foto.BackgroundTask.Info
Returns
dict[str, object] or str
API response with the list of background tasks.
get_background_task_status
Get status for specific background tasks.
Internal API
SYNO.Foto.BackgroundTask.Info
Parameters
task_ids list of str
Task IDs to query.
Returns
dict[str, object] or str
API response with task status details.
get_background_task_error
Get error details for failed background tasks.
Internal API
SYNO.Foto.BackgroundTask.Info
Parameters
task_ids list of str
Task IDs to query.
Returns
dict[str, object] or str
API response with error details for each task.
abort_background_task
Abort running background tasks.
Internal API
SYNO.Foto.BackgroundTask.Info
Parameters
task_ids list of str
Task IDs to abort.
Returns
dict[str, object] or str
API response confirming task abortion.
clear_completed_background_tasks
Remove all completed/failed background tasks from the list.
Internal API
SYNO.Foto.BackgroundTask.Info
Returns
dict[str, object] or str
API response confirming the cleanup.
get_migration_status
Get Photo Station → Synology Photos migration status.
Internal API
SYNO.Foto.Migration
Returns
dict[str, object] or str
API response with migration progress info.
stream_video
Stream a transcoded version of a video (HLS/adaptive).
Uses SYNO.Foto.Streaming. Requires the NAS to have
finished transcoding the video — if the requested quality
is not yet available, this will return None.
For a reliable way to get the raw file regardless of
transcoding state, use :meth:download_video.
Internal API
SYNO.Foto.Streaming
Parameters
unit_id int
The video unit ID.
quality str
Quality level. Known values: "low", "medium",
"high", "original", "mobile".
Default is "original".
dest_path str or None
Where to save the video stream. If None, returns bytes.
Returns
bytes or str or None
Video data, saved file path, or None on failure.
download_video
Download a video from Synology Photos.
Uses SYNO.Foto.Download to retrieve the raw video file.
This is the reliable way to get video content — the
Streaming API requires server-side transcoding and
may not be available for all videos.
Internal API
SYNO.Foto.Download
Parameters
unit_id int
The video unit ID.
dest_path str or None
Where to save the video. If None, returns raw bytes.
Returns
bytes or str or None
Raw video bytes, saved file path, or None on failure.