VideosAPI¶
- class minim.api.tidal.VideosAPI(client: APIClient, /)[source]¶
Bases:
TIDALResourceAPIVideos API endpoints for the TIDAL API.
Important
This class is managed by
TIDALAPIClientand should not be instantiated directly.- Parameters:
- clientminim.api._shared.APIClient
API client instance used to make HTTP requests.
Methods
User Collection Videos > Get Items Relationship: Get TIDAL catalog information for videos in a user collection․ User Collections > Get Videos Relationship: Get TIDAL catalog information for videos in a user's collection.
Videos > Get Albums Relationship: Get TIDAL catalog information for albums containing a video.
Videos > Get Artists Relationship: Get TIDAL catalog information for the artists of a video.
Videos > Get Providers Relationship: Get TIDAL catalog information for the providers of a video.
Videos > Get Thumbnail Relationship: Get TIDAL catalog information for the thumbnail for a video.
Videos > Get Usage Rules Relationship: Get TIDAL catalog information for the usage rules for a video.
Videos > Get Single Video: Get TIDAL catalog information for a video․ Videos > Get Multiple Videos: Get TIDAL catalog information for multiple videos.
User Collection Videos > Delete from Items Relationship: Remove videos from a user collection․ User Collections > Delete from Videos Relationship: Remove videos from a user's collection.
User Collection Videos > Add to Items Relationship: Add videos to a user collection․ User Collections > Add to Videos Relationship: Add videos to a user's collection.
Search Results > Get Videos Relationship: Search for videos in the TIDAL catalog.
- get_user_saved_videos(*, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None, locale: str | None = None, include_metadata: bool = False, cursor: str | None = None, sort_by: str | None = None, descending: bool | None = None) dict[str, Any][source]¶
User Collection Videos > Get Items Relationship: Get TIDAL catalog information for videos in a user collection․ User Collections > Get Videos Relationship: Get TIDAL catalog information for videos in a user’s collection.
Authorization scope
collection.readscopeRead access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
GET /userCollections/{user_id}/relationships/videosendpoint is used.- Parameters:
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- localestr; keyword-only; optional
IETF BCP 47 language tag.
- include_metadatabool; keyword-only; default:
False Whether to include metadata for the videos in the user’s collection.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- sort_bystr; keyword-only; optional
Field to sort the videos by.
Valid values:
"addedAt","artists.name","duration","title".- descendingbool; keyword-only; optional
Whether to sort in descending order.
API default:
False.
- Returns:
- videosdict[str, Any]
Page of TIDAL metadata for the videos in the user’s collection.
Sample response
{ "data": [ { "id": <str>, "meta": { "addedAt": <str> }, "type": "videos" } ], "included": [ { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float> "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "thumbnailArt": { "links": { "self": <str> } } }, "type": "videos" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_video_albums(video_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Videos > Get Albums Relationship: Get TIDAL catalog information for albums containing a video.
- Parameters:
- video_idint or str; positional-only
TIDAL ID of the video.
Examples:
53315642,"75623239".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the albums containing the video.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- albumsdict[str, Any]
Page of TIDAL metadata for the albums containing the videos.
Sample response
{ "data": [ { "id": <str>, "type": "albums" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_video_artists(video_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Videos > Get Artists Relationship: Get TIDAL catalog information for the artists of a video.
- Parameters:
- video_idint or str; positional-only
TIDAL ID of the video.
Examples:
53315642,"75623239".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the video’s artists.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- artistsdict[str, Any]
Page of TIDAL metadata for the video’s artists.
Sample response
{ "data": [ { "id": <str>, "type": "artists" } ], "included": [ { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_video_providers(video_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Videos > Get Providers Relationship: Get TIDAL catalog information for the providers of a video.
- Parameters:
- video_idint or str; positional-only
TIDAL ID of the video.
Examples:
53315642,"75623239".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the video’s providers.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- providersdict[str, Any]
Page of TIDAL metadata for the video’s providers.
Sample response
{ "data": [ { "id": <str>, "type": "providers" } ], "included": [ { "attributes": { "name": <str> }, "id": <str>, "type": "providers" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_video_thumbnail(video_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Videos > Get Thumbnail Relationship: Get TIDAL catalog information for the thumbnail for a video.
- Parameters:
- video_idint or str; positional-only
TIDAL ID of the video.
Examples:
53315642,"75623239".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the video’s thumbnail.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- thumbnaildict[str, Any]
Page of TIDAL metadata for the video’s thumbnail.
Sample response
{ "data": [ { "id": <str>, "type": "artworks" } ], "included": [ { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_video_usage_rules(video_id: int | str, /, *, include_metadata: bool = False, share_code: str | None = None) dict[str, Any][source]¶
Videos > Get Usage Rules Relationship: Get TIDAL catalog information for the usage rules for a video.
- Parameters:
- video_idint or str; positional-only
TIDAL ID of the video.
Examples:
53315642,"75623239".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the track’s usage rules.
- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- usage_rulesdict[str, Any]
TIDAL metadata for the video’s usage rules.
Sample response
{ "data": { "id": <str>, "type": "usageRules" }, "included": [ { "attributes": { "countryCode": <str>, "free": <list[str]>, "paid": <list[str]>,, "subscription": <list[str]>, }, "id": <str>, "type": "usageRules" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_videos(video_ids: int | str | Collection[int | str] | None = None, /, *, isrcs: str | Collection[str] | None = None, country_code: str | None = None, expand: str | Collection[str] | None = None) dict[str, Any][source]¶
Videos > Get Single Video: Get TIDAL catalog information for a video․ Videos > Get Multiple Videos: Get TIDAL catalog information for multiple videos.
User authentication
- User authentication
Access information for a resource’s owners.
Important
Exactly one of video_ids or isrcs must be provided. If video_ids is specified, the request will always be sent to the endpoint for multiple videos.
- Parameters:
- video_idsint, str, or Collection[int | str]; positional-only; optional
TIDAL IDs of the videos.
Examples:
53315642,"75623239",[53315642, "75623239"].- isrcsstr or Collection[str]; keyword-only; optional
International Standard Recording Codes (ISRCs) of the videos.
Examples:
"QMJMT1701237",[QMJMT1701237, "USAT21404265"].- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- expandstr or Collection[str]; keyword-only; optional
Related resources to include metadata for in the response.
Valid values:
"albums","artists","credits","providers","replacement","similarVideos","suggestedVideos","thumbnailArt","usageRules".Examples:
"thumbnailArt",["albums", "artists"].
- Returns:
- videosdict[str, Any]
TIDAL metadata for the videos.
Sample responses
{ "data": { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float>, "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "self": <str> } }, "artists": { "data": [ { "id": <str>, "type": "artists" } ], "links": { "self": <str> } }, "providers": { "data": [ { "id": <str>, "type": "providers" } ], "links": { "self": <str> } }, "thumbnailArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } } }, "type": "videos" }, "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" }, { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "name": <str> }, "id": <str>, "type": "providers" } ], "links": { "self": <str> } }
{ "data": [ { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float>, "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "self": <str> } }, "artists": { "data": [ { "id": <str>, "type": "artists" } ], "links": { "self": <str> } }, "providers": { "data": [ { "id": <str>, "type": "providers" } ], "links": { "self": <str> } }, "thumbnailArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } } }, "type": "videos" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" }, { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "name": <str> }, "id": <str>, "type": "providers" } ], "links": { "self": <str> } }
- remove_saved_videos(video_ids: str | dict[str, int | str] | Collection[int | str | dict[str, int | str]], /, *, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None) None[source]¶
User Collection Videos > Delete from Items Relationship: Remove videos from a user collection․ User Collections > Delete from Videos Relationship: Remove videos from a user’s collection.
Authorization scope
collection.writescopeWrite access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
DELETE /userCollections/{user_id}/relationships /videosendpoint is used.- Parameters:
- video_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the videos.
Examples:
53315642"75623239"{"id": "75623239", "types": "videos"}["53315642", {"id": "75623239", "types": "videos"}]
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- save_videos(video_ids: str | dict[str, int | str] | Collection[int | str | dict[str, int | str]], /, *, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None) None[source]¶
User Collection Videos > Add to Items Relationship: Add videos to a user collection․ User Collections > Add to Videos Relationship: Add videos to a user’s collection.
Authorization scope
collection.writescopeWrite access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
POST /userCollections/{user_id}/relationships/videosendpoint is used.- Parameters:
- video_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the videos.
Examples:
53315642"75623239"{"id": "75623239", "types": "videos"}["53315642", {"id": "75623239", "types": "videos"}]
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".
- search_videos(query: str, /, country_code: str | None = None, *, include_explicit: bool | None = None, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Search Results > Get Videos Relationship: Search for videos in the TIDAL catalog.
Authorization scope
search.readscopeRead personalized search results.
- Parameters:
- querystr; positional-only
Search query.
- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_explicitbool; keyword-only; optional
Whether to include items with explicit language.
API default:
True.- include_metadatabool; keyword-only; default:
False Whether to include metadata for the matching videos.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- videosdict[str, Any]
Page of TIDAL metadata for the matching videos.
Sample response
{ "data": [ { "id": <str>, "type": "videos" } ], "included": [ { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc":<str>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "version": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "thumbnailArt": { "links": { "self": <str> } } }, "type": "videos" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }