feat: add endpoints for fetching and uploading posters/artwork

2025-12-10 04:20:52 +00:00 · 2025-04-02 21:26:32 +01:00
parent 092b953ea2
commit 1a2eeccb56
7 changed files with 1301 additions and 0 deletions
--- a/src/paths/library/metadata/[ratingKey]/arts/get-media-arts.yaml
+++ b/src/paths/library/metadata/[ratingKey]/arts/get-media-arts.yaml
@@ -0,0 +1,64 @@
+tags:
+  - Library
+summary: Get Media Background Artwork
+description: Returns the background artwork for a library item.
+operationId: get-media-arts
+parameters:
+  - name: ratingKey
+    in: path
+    description: the id of the library item to return the artwork of.
+    schema:
+      type: integer
+      example: 16099
+    required: true
+responses:
+  "200":
+    description: The available background artwork for the library item.
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            MediaContainer:
+              allOf:
+                - $ref: "../../../../../models/media-container/size.yaml"
+                - $ref: "../../../../../models/media-container/media-tag-version.yaml"
+                - $ref: "../../../../../models/media-container/media-tag-prefix.yaml"
+                - $ref: "../../../../../models/media-container/identifier.yaml"
+                - type: object
+                  required:
+                    - Metadata
+                  properties:
+                    Metadata:
+                      type: array
+                      items:
+                        type: object
+                        required:
+                          - key
+                          - ratingKey
+                          - selected
+                          - thumb
+                        properties:
+                          key:
+                            type: string
+                            description: The URL of the artwork.
+                            example: https://image.tmdb.org/t/p/original/ixgFmf1X59PUZam2qbAfskx2gQr.jpg
+                          provider:
+                            type: string
+                            description: The provider of the artwork.
+                            example: tmdb
+                          ratingKey:
+                            type: string
+                            description: The URL of the artwork.
+                            example: https://image.tmdb.org/t/p/original/ixgFmf1X59PUZam2qbAfskx2gQr.jpg
+                          selected:
+                            type: boolean
+                            description: Whether this is the selected artwork.
+                            example: true
+                          thumb:
+                            type: string
+                            description: The URL of the artwork thumbnail.
+                            example: https://images.plex.tv/photo?height=270&width=480&minSize=1&upscale=1&url=https%3A%2F%2Fimage%2Etmdb%2Eorg%2Ft%2Fp%2Foriginal%2FixgFmf1X59PUZam2qbAfskx2gQr%2Ejpg
+
+  "404":
+    $ref: "../../../../../responses/404-html.yaml"
--- a/src/paths/library/metadata/[ratingKey]/arts/post-media-arts.yaml
+++ b/src/paths/library/metadata/[ratingKey]/arts/post-media-arts.yaml
@@ -0,0 +1,34 @@
+tags:
+  - Library
+summary: Upload Media Background Artwork
+description: Uploads an image to use as the background artwork for a library item, either from a local file or a remote URL
+operationId: post-media-arts
+parameters:
+  - name: ratingKey
+    in: path
+    description: the id of the library item to return the posters of.
+    schema:
+      type: integer
+      example: 2268
+    required: true
+  - name: url
+    in: query
+    description: The URL of the image, if uploading a remote image
+    schema:
+      type: string
+      example: https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
+    required: false
+requestBody:
+  description: The contents of the image, if uploading a local file
+  content:
+    image/*:
+      schema:
+        type: string
+        format: binary
+
+responses:
+  "200":
+    description: The background artwork was uploaded successfully.
+
+  "404":
+    $ref: "../../../../../responses/404-html.yaml"
--- a/src/paths/library/metadata/[ratingKey]/posters/get-media-posters.yaml
+++ b/src/paths/library/metadata/[ratingKey]/posters/get-media-posters.yaml
@@ -0,0 +1,64 @@
+tags:
+  - Library
+summary: Get Media Posters
+description: Returns the available posters for a library item.
+operationId: get-media-posters
+parameters:
+  - name: ratingKey
+    in: path
+    description: the id of the library item to return the posters of.
+    schema:
+      type: integer
+      example: 16099
+    required: true
+responses:
+  "200":
+    description: The available posters for the library item.
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            MediaContainer:
+              allOf:
+                - $ref: "../../../../../models/media-container/size.yaml"
+                - $ref: "../../../../../models/media-container/media-tag-version.yaml"
+                - $ref: "../../../../../models/media-container/media-tag-prefix.yaml"
+                - $ref: "../../../../../models/media-container/identifier.yaml"
+                - type: object
+                  required:
+                    - Metadata
+                  properties:
+                    Metadata:
+                      type: array
+                      items:
+                        type: object
+                        required:
+                          - key
+                          - ratingKey
+                          - selected
+                          - thumb
+                        properties:
+                          key:
+                            type: string
+                            description: The URL of the poster.
+                            example: https://image.tmdb.org/t/p/original/hntBJjqbv4m0Iyniqaztv9xaudI.jpg
+                          provider:
+                            type: string
+                            description: The provider of the poster.
+                            example: tmdb
+                          ratingKey:
+                            type: string
+                            description: The URL of the poster.
+                            example: https://image.tmdb.org/t/p/original/hntBJjqbv4m0Iyniqaztv9xaudI.jpg
+                          selected:
+                            type: boolean
+                            description: Whether this is the selected poster.
+                            example: true
+                          thumb:
+                            type: string
+                            description: The URL of the poster thumbnail.
+                            example: https://images.plex.tv/photo?height=336&width=225&minSize=1&upscale=1&url=https%3A%2F%2Fimage%2Etmdb%2Eorg%2Ft%2Fp%2Foriginal%2FhntBJjqbv4m0Iyniqaztv9xaudI%2Ejpg
+
+  "404":
+    $ref: "../../../../../responses/404-html.yaml"
--- a/src/paths/library/metadata/[ratingKey]/posters/post-media-poster.yaml
+++ b/src/paths/library/metadata/[ratingKey]/posters/post-media-poster.yaml
@@ -0,0 +1,34 @@
+tags:
+  - Library
+summary: Upload Media Poster
+description: Uploads a poster to a library item, either from a local file or a remote URL
+operationId: post-media-poster
+parameters:
+  - name: ratingKey
+    in: path
+    description: the id of the library item to return the posters of.
+    schema:
+      type: integer
+      example: 2268
+    required: true
+  - name: url
+    in: query
+    description: The URL of the image, if uploading a remote image
+    schema:
+      type: string
+      example: https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
+    required: false
+requestBody:
+  description: The contents of the image, if uploading a local file
+  content:
+    image/*:
+      schema:
+        type: string
+        format: binary
+
+responses:
+  "200":
+    description: The poster was uploaded successfully.
+
+  "404":
+    $ref: "../../../../../responses/404-html.yaml"