> ## Documentation Index
> Fetch the complete documentation index at: https://personal-92-migrate-dev-docs-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcode an image

> Transcode an image, possibly changing format or size



## OpenAPI

````yaml /openapi-with-code-samples.yaml get /photo/:/transcode
openapi: 3.1.1
info:
  title: Plex Media Server
  version: 1.1.1
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://{IP-description}.{identifier}.plex.direct:{port}
    variables:
      identifier:
        description: The unique identifier of this particular PMS
        default: 0123456789abcdef0123456789abcdef
      IP-description:
        description: A `-` separated string of the IPv4 or IPv6 address components
        default: 1-2-3-4
      port:
        default: '32400'
  - url: '{protocol}://{host}:{port}'
    variables:
      protocol:
        description: The network protocol to use. Typically (`http` or `https`)
        default: http
      host:
        description: >
          The Host of the PMS.

          If using on a local network, this is the internal IP address of the
          server hosting the PMS.

          If using on an external network, this is the external IP address for
          your network, and requires port forwarding.

          If using a reverse proxy, this would be the external DNS domain for
          your network, and requires the proxy handle port forwarding. 
        default: localhost
      port:
        description: >
          The Port number configured on the PMS. Typically (`32400`). 

          If using a reverse proxy, this would be the port number configured on
          the proxy.
        default: '32400'
  - url: '{full_server_url}'
    variables:
      full_server_url:
        description: The full manual URL to access the PMS
        default: http://localhost:32400
security:
  - token:
      - shared user
      - admin
tags:
  - name: Activities
    description: >
      Activities provide a way to monitor and control asynchronous operations on
      the server. In order to receive real-time updates for activities, a client
      would normally subscribe via either EventSource or Websocket endpoints.


      Activities are associated with HTTP replies via a special
      `X-Plex-Activity` header which contains the UUID of the activity.


      Activities are optional cancellable. If cancellable, they may be cancelled
      via the `DELETE` endpoint.
  - name: Butler
    description: >-
      The butler is responsible for running periodic tasks.  Some tasks run
      daily, others every few days, and some weekly.  These includes database
      maintenance, metadata updating, thumbnail generation, media analysis, and
      other tasks.
  - name: Collections
    description: API Operations against the Collections
  - name: Content
    description: The actual content of the media provider
  - name: Devices
    description: >
      Media grabbers provide ways for media to be obtained for a given protocol.
      The simplest ones are `stream` and `download`. More complex grabbers can
      have associated devices


      Network tuners can present themselves on the network using the Simple
      Service Discovery Protocol and Plex Media Server will discover them. The
      following XML is an example of the data returned from SSDP. The
      `deviceType`, `serviceType`, and `serviceId` values must remain as they
      are in the example in order for PMS to properly discover the device. Other
      less-obvious fields are described in the parameters section below.


      Example SSDP output

      ```

      <root xmlns="urn:schemas-upnp-org:device-1-0">
          <specVersion>
              <major>1</major>
              <minor>0</minor>
          </specVersion>
          <device>
              <deviceType>urn:plex-tv:device:Media:1</deviceType>
              <friendlyName>Turing Hopper 3000</friendlyName>
              <manufacturer>Plex, Inc.</manufacturer>
              <manufacturerURL>https://plex.tv/</manufacturerURL>
              <modelDescription>Turing Hopper 3000 Media Grabber</modelDescription>
              <modelName>Plex Media Grabber</modelName>
              <modelNumber>1</modelNumber>
              <modelURL>https://plex.tv</modelURL>
              <UDN>uuid:42fde8e4-93b6-41e5-8a63-12d848655811</UDN>
              <serviceList>
                  <service>
                      <URLBase>http://10.0.0.5:8088</URLBase>
                      <serviceType>urn:plex-tv:service:MediaGrabber:1</serviceType>
                      <serviceId>urn:plex-tv:serviceId:MediaGrabber</serviceId>
                  </service>
              </serviceList>
          </device>
      </root>

      ```

        - UDN: (string) A UUID for the device. This should be unique across models of a device at minimum.
        - URLBase: (string) The base HTTP URL for the device from which all of the other endpoints are hosted.
  - name: Download Queue
    description: API Operations against the Download Queue
  - name: DVRs
    description: >
      The DVR provides means to watch and record live TV.  This section of
      endpoints describes how to setup the DVR itself
  - name: EPG
    description: >
      The EPG (Electronic Program Guide) is responsible for obtaining metadata
      for what is airing on each channel and when
  - name: Events
    description: >
      The server can notify clients in real-time of a wide range of events, from
      library scanning, to preferences being modified, to changes to media, and
      many other things. This is also the mechanism by which activity progress
      is reported.


      Two protocols for receiving the events are available: EventSource (also
      known as SSE), and WebSocket.
  - name: General
    description: >-
      General endpoints for basic PMS operation not specific to any media
      provider
  - name: Hubs
    description: The hubs within a media provider
  - name: Library
    description: >-
      Library endpoints which are outside of the Media Provider API.  Typically
      this is manipulation of the library (adding/removing sections, modifying
      preferences, etc).
  - name: Library Collections
    description: >-
      Endpoints for manipulating collections.  In addition to these endpoints,
      `/library/collections/:collectionId/X` will be rerouted to
      `/library/metadata/:collectionId/X` and respond to those endpoints as
      well.
    x-displayName: 'Library: Collections'
  - name: Library Playlists
    description: Endpoints for manipulating playlists.
    x-displayName: 'Library: Playlists'
  - name: Live TV
    description: |
      LiveTV contains the playback sessions of a channel from a DVR device
  - name: Log
    description: Logging mechanism to allow clients to log to the server
  - name: Play Queue
    description: >-
      The playqueue feature within a media provider

      A play queue represents the current list of media for playback. Although
      queues are persisted by the server, they should be regarded by the user as
      a fairly lightweight, an ephemeral list of items queued up for playback in
      a session.  There is generally one active queue for each type of media
      (music, video, photos) that can be added to or destroyed and replaced with
      a fresh queue.

      Play Queues has a region, which we refer to in this doc (partially for
      historical reasons) as "Up Next". This region is defined by
      `playQueueLastAddedItemID` existing on the media container. This follows
      iTunes' terminology. It is a special region after the currently playing
      item but before the originally-played items. This enables "Party Mode"
      listening/viewing, where items can be added on-the-fly, and normal queue
      playback resumed when completed. 

      You can visualize the play queue as a sliding window in the complete list
      of media queued for playback. This model is important when scaling to
      larger play queues (e.g. shuffling 40,000 audio tracks). The client only
      needs visibility into small areas of the queue at any given time, and the
      server can optimize access in this fashion.

      All created play queues will have an empty "Up Next" area - unless the
      item is an album and no `key` is provided. In this case the "Up Next" area
      will be populated by the contents of the album. This is to allow queueing
      of multiple albums - since the 'Add to Up Next' will insert after all the
      tracks. This means that If you're creating a PQ from an album, you can
      only shuffle it if you set `key`. This is due to the above implicit
      queueing of albums when no `key` is provided as well as the current
      limitation that you cannot shuffle a PQ with an "Up Next" area.

      The play queue window advances as the server receives timeline requests.
      The client needs to retrieve the play queue as the “now playing” item
      changes. There is no play queue API to update the playing item.
  - name: Playlist
    description: Media playlists that can be created and played back
  - name: Preferences
    description: API Operations against the Preferences
  - name: Provider
    description: >-
      Media providers are the starting points for the entire Plex Media Server
      media library API.  It defines the paths for the groups of endpoints.  The
      `/media/providers` should be the only hard-coded path in clients when
      accessing the media library.  Non-media library endpoints are outside the
      scope of the media provider.  See the description in See [the section in
      API Info](#section/API-Info/Media-Providers) for more information on how
      to use media providers.
  - name: Rate
    description: Operations for rating media items (thumbs up/down, star ratings, etc.)
  - name: Search
    description: The search feature within a media provider
  - name: Status
    description: >-
      The status endpoints give you information about current playbacks, play
      history, and even terminating sessions.
  - name: Subscriptions
    description: >
      Subscriptions determine which media will be recorded and the criteria for
      selecting an airing when multiple are available
  - name: Timeline
    description: The actions feature within a media provider
  - name: Transcoder
    description: API Operations against the Transcoder
  - name: UltraBlur
    description: Service provided to compute UltraBlur colors and images.
  - name: Updater
    description: >
      This describes the API for searching and applying updates to the Plex
      Media Server.

      Updates to the status can be observed via the Event API.
paths:
  /photo/:/transcode:
    get:
      tags:
        - Transcoder
      summary: Transcode an image
      description: Transcode an image, possibly changing format or size
      operationId: transcodeImage
      parameters:
        - $ref: '#/components/parameters/accepts'
        - $ref: '#/components/parameters/X-Plex-Client-Identifier'
        - $ref: '#/components/parameters/X-Plex-Product'
        - $ref: '#/components/parameters/X-Plex-Version'
        - $ref: '#/components/parameters/X-Plex-Platform'
        - $ref: '#/components/parameters/X-Plex-Platform-Version'
        - $ref: '#/components/parameters/X-Plex-Device'
        - $ref: '#/components/parameters/X-Plex-Model'
        - $ref: '#/components/parameters/X-Plex-Device-Vendor'
        - $ref: '#/components/parameters/X-Plex-Device-Name'
        - $ref: '#/components/parameters/X-Plex-Marketplace'
        - name: url
          description: >-
            The source URL for the image to transcode.  Note, if this URL
            requires a token such as `X-Plex-Token`, it should be given as a
            query parameter to this url.
          in: query
          schema:
            type: string
          example: /library/metadata/265/thumb/1715112705
        - name: format
          description: The output format for the image; defaults to jpg
          in: query
          required: false
          schema:
            type: string
            enum:
              - jpg
              - jpeg
              - png
              - ppm
        - name: width
          description: The desired width of the output image
          in: query
          schema:
            type: integer
        - name: height
          description: The desired height of the output image
          in: query
          schema:
            type: integer
        - name: quality
          description: >-
            The desired quality of the output.  -1 means the highest quality. 
            Defaults to -1
          in: query
          required: false
          schema:
            maximum: 127
            minimum: -1
            type: integer
        - name: background
          description: >-
            The background color to apply before painting the image.  Only
            really applicable if image has transparency.  Defaults to none
          in: query
          required: false
          schema:
            type: string
          example: '#ff5522'
        - name: upscale
          description: >-
            Indicates if image should be upscaled to the desired width/height. 
            Defaults to false
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BoolInt'
        - name: minSize
          description: >-
            Indicates if image should be scaled to fit the smaller dimension. 
            By default (false) the image is scaled to fit within the
            width/height specified but if this parameter is true, it will allow
            overflowing one dimension to fit the other.  Essentially it is
            making the width/height minimum sizes of the image or sizing the
            image to fill the entire width/height even if it overflows one
            dimension.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BoolInt'
        - name: rotate
          description: Obey the rotation values specified in EXIF data.  Defaults to true.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BoolInt'
        - name: blur
          description: Apply a blur to the image, Defaults to 0 (none)
          in: query
          required: false
          schema:
            type: integer
        - name: saturation
          description: >-
            Scale the image saturation by the specified percentage.  Defaults to
            100
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 0
            type: integer
        - name: opacity
          description: >-
            Render the image at the specified opacity percentage.  Defaults to
            100
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 0
            type: integer
        - name: chromaSubsampling
          description: |-
            Use the specified chroma subsambling.
              - 0: 411
              - 1: 420
              - 2: 422
              - 3: 444
            Defaults to 3 (444)
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
        - name: blendColor
          description: The color to blend with the image.  Defaults to none
          in: query
          required: false
          schema:
            type: string
          example: '#ff5522'
      responses:
        '200':
          description: The resulting image
          content:
            image/jpeg:
              schema:
                format: binary
                type: string
            image/png:
              schema:
                format: binary
                type: string
            image/x-portable-pixmap:
              schema:
                format: binary
                type: string
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      x-codeSamples:
        - lang: php
          label: PlexPHP
          source: |-
            declare(strict_types=1);

            require 'vendor/autoload.php';

            use LukeHagar\Plex_API;
            use LukeHagar\Plex_API\Models\Operations;

            $sdk = Plex_API\PlexAPI::builder()
                ->setSecurity(
                    '<YOUR_API_KEY_HERE>'
                )
                ->build();

            $request = new Operations\GetResizedPhotoRequest(
                width: 110,
                height: 165,
                blur: 0,
                minSize: Operations\MinSize::Zero,
                upscale: Operations\Upscale::Zero,
                url: '/library/metadata/49564/thumb/1654258204',
            );

            $response = $sdk->server->getResizedPhoto(
                request: $request
            );

            if ($response->statusCode === 200) {
                // handle response
            }
        - lang: ruby
          label: PlexRuby
          source: |-
            require 'plex_ruby_sdk'

            s = ::PlexRubySDK::PlexAPI.new(
                  security: Models::Shared::Security.new(
                    access_token: "<YOUR_API_KEY_HERE>",
                  ),
                )

            req = Models::Operations::GetResizedPhotoRequest.new(
              width: 110.0,
              height: 165.0,
              opacity: 643_869,
              blur: 0.0,
              min_size: Models::Operations::MinSize::ONE,
              upscale: Models::Operations::Upscale::ONE,
              url: "/library/metadata/49564/thumb/1654258204",
            )

            res = s.server.get_resized_photo(req)

            if res.status_code == 200
              # handle response
            end
        - lang: go
          label: PlexGO
          source: "package main\n\nimport(\n\t\"context\"\n\t\"github.com/LukeHagar/plexgo/models/components\"\n\t\"github.com/LukeHagar/plexgo\"\n\t\"github.com/LukeHagar/plexgo/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    s := plexgo.New(\n        plexgo.WithAccepts(components.AcceptsApplicationXML),\n        plexgo.WithClientIdentifier(\"abc123\"),\n        plexgo.WithProduct(\"Plex for Roku\"),\n        plexgo.WithVersion(\"2.4.1\"),\n        plexgo.WithPlatform(\"Roku\"),\n        plexgo.WithPlatformVersion(\"4.3 build 1057\"),\n        plexgo.WithDevice(\"Roku 3\"),\n        plexgo.WithModel(\"4200X\"),\n        plexgo.WithDeviceVendor(\"Roku\"),\n        plexgo.WithDeviceName(\"Living Room TV\"),\n        plexgo.WithMarketplace(\"googlePlay\"),\n        plexgo.WithSecurity(\"<YOUR_API_KEY_HERE>\"),\n    )\n\n    res, err := s.Transcoder.TranscodeImage(ctx, operations.TranscodeImageRequest{\n        URL: plexgo.Pointer(\"/library/metadata/265/thumb/1715112705\"),\n        Background: plexgo.Pointer(\"#ff5522\"),\n        Upscale: components.BoolIntTrue.ToPointer(),\n        MinSize: components.BoolIntTrue.ToPointer(),\n        Rotate: components.BoolIntTrue.ToPointer(),\n        BlendColor: plexgo.Pointer(\"#ff5522\"),\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.TwoHundredImageJpegResponseStream != nil {\n        // handle response\n    }\n}"
        - lang: java
          label: PlexJava
          source: |-
            package hello.world;

            import dev.plexapi.sdk.PlexAPI;
            import dev.plexapi.sdk.models.operations.TranscodeImageRequest;
            import dev.plexapi.sdk.models.operations.TranscodeImageResponse;
            import dev.plexapi.sdk.models.shared.Accepts;
            import dev.plexapi.sdk.models.shared.BoolInt;
            import java.lang.Exception;

            public class Application {

                public static void main(String[] args) throws Exception {

                    PlexAPI sdk = PlexAPI.builder()
                            .accepts(Accepts.APPLICATION_XML)
                            .clientIdentifier("abc123")
                            .product("Plex for Roku")
                            .version("2.4.1")
                            .platform("Roku")
                            .platformVersion("4.3 build 1057")
                            .device("Roku 3")
                            .model("4200X")
                            .deviceVendor("Roku")
                            .deviceName("Living Room TV")
                            .marketplace("googlePlay")
                            .token(System.getenv().getOrDefault("TOKEN", ""))
                        .build();

                    TranscodeImageRequest req = TranscodeImageRequest.builder()
                            .url("/library/metadata/265/thumb/1715112705")
                            .background("#ff5522")
                            .upscale(BoolInt.True)
                            .minSize(BoolInt.True)
                            .rotate(BoolInt.True)
                            .blendColor("#ff5522")
                            .build();

                    TranscodeImageResponse res = sdk.transcoder().transcodeImage()
                            .request(req)
                            .call();

                    if (res.twoHundredImageJpegResponseStream().isPresent()) {
                        // handle response
                    }
                }
            }
        - lang: typescript
          label: PlexJS
          source: |-
            import { PlexAPI } from "@lukehagar/plexjs";
            import { Accepts, BoolInt } from "@lukehagar/plexjs/models/shared";

            const plexAPI = new PlexAPI({
              accepts: Accepts.ApplicationXml,
              clientIdentifier: "abc123",
              product: "Plex for Roku",
              version: "2.4.1",
              platform: "Roku",
              platformVersion: "4.3 build 1057",
              device: "Roku 3",
              model: "4200X",
              deviceVendor: "Roku",
              deviceName: "Living Room TV",
              marketplace: "googlePlay",
              token: "<YOUR_API_KEY_HERE>",
            });

            async function run() {
              const result = await plexAPI.transcoder.transcodeImage({
                url: "/library/metadata/265/thumb/1715112705",
                background: "#ff5522",
                upscale: BoolInt.True,
                minSize: BoolInt.True,
                rotate: BoolInt.True,
                blendColor: "#ff5522",
              });

              console.log(result);
            }

            run();
components:
  parameters:
    accepts:
      name: accepts
      description: Indicates the client accepts the indicated media types
      in: header
      schema:
        type: string
        default: application/xml
        enum:
          - application/json
          - application/xml
    X-Plex-Client-Identifier:
      name: X-Plex-Client-Identifier
      x-speakeasy-name-override: Client-Identifier
      in: header
      description: An opaque identifier unique to the client
      required: true
      schema:
        type: string
        example: abc123
      example: abc123
    X-Plex-Product:
      name: X-Plex-Product
      x-speakeasy-name-override: Product
      in: header
      description: The name of the client product
      schema:
        type: string
        example: Plex for Roku
      example: Plex for Roku
    X-Plex-Version:
      name: X-Plex-Version
      x-speakeasy-name-override: Version
      in: header
      description: The version of the client application
      schema:
        type: string
        example: 2.4.1
      example: 2.4.1
    X-Plex-Platform:
      name: X-Plex-Platform
      x-speakeasy-name-override: Platform
      in: header
      description: The platform of the client
      schema:
        type: string
        example: Roku
      example: Roku
    X-Plex-Platform-Version:
      name: X-Plex-Platform-Version
      x-speakeasy-name-override: Platform-Version
      in: header
      description: The version of the platform
      schema:
        type: string
        example: 4.3 build 1057
      example: 4.3 build 1057
    X-Plex-Device:
      name: X-Plex-Device
      x-speakeasy-name-override: Device
      in: header
      description: A relatively friendly name for the client device
      schema:
        type: string
        example: Roku 3
      example: Roku 3
    X-Plex-Model:
      name: X-Plex-Model
      x-speakeasy-name-override: Model
      in: header
      description: A potentially less friendly identifier for the device model
      schema:
        type: string
        example: 4200X
      example: 4200X
    X-Plex-Device-Vendor:
      name: X-Plex-Device-Vendor
      x-speakeasy-name-override: Device-Vendor
      in: header
      description: The device vendor
      schema:
        type: string
        example: Roku
      example: Roku
    X-Plex-Device-Name:
      name: X-Plex-Device-Name
      x-speakeasy-name-override: Device-Name
      in: header
      description: A friendly name for the client
      schema:
        type: string
        example: Living Room TV
      example: Living Room TV
    X-Plex-Marketplace:
      name: X-Plex-Marketplace
      x-speakeasy-name-override: Marketplace
      in: header
      description: The marketplace on which the client application is distributed
      schema:
        type: string
        example: googlePlay
      example: googlePlay
  schemas:
    BoolInt:
      type: integer
      format: int32
      enum:
        - 0
        - 1
      example: 1
      default: 0
      x-speakeasy-enums:
        - false
        - true
  responses:
    '400':
      description: Bad Request
      content:
        text/html: {}
    '403':
      description: Forbidden
      content:
        text/html: {}
    '404':
      description: Not Found
      content:
        text/html: {}
  securitySchemes:
    token:
      name: X-Plex-Token
      description: >
        The token which identifies the user accessing the PMS. This can be
        either:

        - A traditional access token obtained from plex.tv

        - A JWT token obtained through the JWT authentication flow


        JWT tokens provide better security with:

        - Short-lived tokens (7 days expiration)

        - Public-key cryptography (ED25519)

        - Better clock synchronization

        - Individual device revocation capability
      type: apiKey
      in: header

````