Skip to content

Developers

How can we help you?

← Go back

Image

Note: This resource links can be expanded using the expand option.

The Image resource represents all of the images associated to a title, a title group, brand or contributor, like posters, box covers, thumbnails, etc.

We’re going to explain how to manipulate images associated with a title but you can do the same with images associated with title groups, brands and contributors.

In Mediagenix On-Demand land, an image looks like this:

<?xml version='1.0' encoding='utf-8' ?>
<image>
  <id type="integer">1</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>jpeg</encoding>
  <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
  <type>Poster</type>
  <file-name>movie.jpg</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1238791dhskajhfskajsfh</file-md5>
  <is-cover type="boolean">false</is-cover>
  <link rel="self" href="https://movida.bebanjo.net/api/images/1"/>
  <link rel="file" href="https://movida-s3.amazonaws.com/images/attachments/1/original/1562765782-6c8668dc7bb5138962d1b65162177bfbeac2875a.jpg"/>
  <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
</image>

{
  "resource_type": "image",
  "id": 1,
  "external_id": "ABCD9982",
  "width": 1280,
  "height": 720,
  "encoding": "jpeg",
  "aspect_ratio": "16:9",
  "type": "Poster",
  "file_name": "movie.jpg",
  "file_size": 2345569434,
  "file_md5": "1238791dhskajhfskajsfh",
  "is_cover": false,
  "self_link": "https://movida.bebanjo.net/api/images/1",
  "file_link": "https://movida-s3.amazonaws.com/images/attachments/1/original/1562765782-6c8668dc7bb5138962d1b65162177bfbeac2875a.jpg",
  "content_link": "https://movida.bebanjo.net/api/titles/45606",
  "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
  "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
}

Valid attributes

  • id (required): Mediagenix On-Demand internal identifier of the image. It shouldn’t be provided in the creation of the resource, because Mediagenix On-Demand will assign that value.

  • external-id (optional): the identifier of the image in the external system. If provided, it has to be unique in the scope of the company.

  • encoding (required): encoding of the image. Valid values are: tif, tiff, gif, jpeg, jpg, png, pdf, and bmp.

  • width (optional): width size of the image

  • height (optional): height size of the image

  • aspect-ratio (optional): aspect ratio of the image. The separator must be ‘:’ or ‘/’. Use the separator ‘:’ when the aspect ratio of the image is one of the following standards: “3:4”, “4:3”, “3:2”, “16:9”, “1.85:1”, “2.39:1” or “2.40:1”. This attribute will be overwritten with a calculated value when a image file is provided, so you may want to use this attribute only when a image file is not provided.

  • type (optional): the type of the image. There isn’t a closed list of values

  • file-name (optional): the name of the file

  • file-size (optional): the size of the file

  • file-md5 (optional): the MD5 of the file

  • is-cover (optional): whether the image should be used as the default cover art in the Catalogue for the Title, Title Group or Brand it’s associated with. The default value is false.

  • link to the file (optional): the URL to the image file in the cloud storage

Get a list of all images

Images are linked from the root of the API, through the link identified with the rel="images" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="images" href="https://movida.bebanjo.net/api/images">
  <!-- ... -->
</movida>

{
  "resource_type": "movida",
  // ...
  "images_link": "https://movida.bebanjo.net/api/images",
  // ...
}

Following that link, we can fetch the list of images in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/images

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/images

And would yield something like:

<?xml version="1.0" encoding="UTF-8"?>
<images type="array">
  <total-entries>2120</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/images?page=2"/>
  <image>
    <id type="integer">1</id>
    <external_id>ABCD9982</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
    <type>Poster</type>
    <file-name>movie.jpg</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1238791dhskajhfskajsfh</file-md5>
    <is-cover type="boolean">false</is-cover>
    <link rel="self" href="https://movida.bebanjo.net/api/images/1"/>
    <link rel="file" href="https://movida-cloud-image-storage.com/images/343421421-as21232.jpg"/>
    <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
  </image>
  <image>
    <id type="integer">7</id>
    <external_id>ABCD9983</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
    <type>BoxCover</type>
    <file-name>dvd_cover.jpg</file-name>
    <file-size type="integer">234556943</file-size>
    <file-md5>1238791dhskajhfskajsft</file-md5>
    <is-cover type="boolean">true</is-cover>
    <link rel="self" href="https://movida.bebanjo.net/api/images/7"/>
    <link rel="file" href="https://movida-cloud-image-storage.com/images/787324656-es43979.jpg"/>
    <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/7/target_platforms"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/images/7/metadata"/>
  </image>
  <!-- ... -->
</images>

{
  "total_entries": 2120,
  "entries": [
    {
      "resource_type": "image",
      "id": 1,
      "external_id": "ABCD9982",
      "width": 1280,
      "height": 720,
      "encoding": "jpeg",
      "aspect_ratio": "16:9",
      "type": "Poster",
      "file_name": "movie.jpg",
      "file_size": 2345569434,
      "file_md5": "1238791dhskajhfskajsfh",
      "is_cover": false,
      "self_link": "https://movida.bebanjo.net/api/images/1",
      "file_link": "https://movida-cloud-image-storage.com/images/343421421-as21232.jpg",
      "content_link": "https://movida.bebanjo.net/api/titles/45606",
      "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
      "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
    },
    {
      "resource_type": "image",
      "id": 7,
      "external_id": "ABCD9983",
      "width": 1280,
      "height": 720,
      "encoding": "jpeg",
      "aspect_ratio": "16:9",
      "type": "BoxCover",
      "file_name": "dvd_cover.jpg",
      "file_size": 234556943,
      "file_md5": "1238791dhskajhfskajsft",
      "is_cover": true,
      "self_link": "https://movida.bebanjo.net/api/images/7",
      "file_link": "https://movida-cloud-image-storage.com/images/343421421-as21232.jpg",
      "content_link": "https://movida.bebanjo.net/api/titles/45606",
      "target_platforms_link": "https://movida.bebanjo.net/api/images/7/target_platforms",
      "metadata_link": "https://movida.bebanjo.net/api/images/7/metadata"
    },
    // ...
  ]
}

Note: This is a paginated resource. By default, only 50 images will be included in each page but you can override this default by using the per_page parameter described in the next section. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

You can filter the list of images returned using the following attributes:

  • external_id: You can filter the list of images by passing in an external_id. Because Mediagenix On-Demand was designed to integrate with external content management system, it has an attribute called external_id for every image. This attribute can be used to store the ID of that specific item in an external system.

  • per_page – Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get an image by external_id

If you needed to access an image by external_id, you can do so by passing the parameter external_id to the list of images, like this:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/images?external_id=ABCD9982

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/images?external_id=ABCD9982

Which would filter by the passed external_id like:

<?xml version="1.0" encoding="UTF-8"?>
<images type="array">
  <total-entries>1</total-entries>
  <image>
    <id type="integer">1</id>
    <external_id>ABCD9982</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
    <type>Poster</type>
    <file-name>movie.jpg</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1238791dhskajhfskajsfh</file-md5>
    <is-cover type="boolean">false</is-cover>
    <link rel="self" href="https://movida.bebanjo.net/api/images/1"/>
    <link rel="file" href="https://movida-cloud-image-storage.com/images/343421421-as21232.jpg"/>
    <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
  </image>
</images>

{
  "total_entries": 1,
  "entries": [
    {
      "resource_type": "image",
      "id": 1,
      "external_id": "ABCD9982",
      "width": 1280,
      "height": 720,
      "encoding": "jpeg",
      "aspect_ratio": "16:9",
      "type": "Poster",
      "file_name": "movie.jpg",
      "file_size": 2345569434,
      "file_md5": "1238791dhskajhfskajsfh",
      "is_cover": false,
      "self_link": "https://movida.bebanjo.net/api/images/1",
      "file_link": "https://movida-cloud-image-storage.com/images/343421421-as21232.jpg",
      "content_link": "https://movida.bebanjo.net/api/titles/45606",
      "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
      "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
    }
  ]
}

Get a List of all images of a title

Images are accessed via a Title. Refer to the title page to find out how to access a Title. Inside a Title, one of the related link nodes is the images node, identified by the rel attribute. Like here:

<?xml version='1.0' encoding='utf-8' ?>
<title>
  <!-- ... -->
  <link rel="images" href="https://movida.bebanjo.net/api/titles/45606/images"/>
  <!-- ... -->
</title>

{
  "resource_type": "title",
  // ...
  "images_link": "https://movida.bebanjo.net/api/titles/2906491/images",
  // ...
}

If we follow that link we can fetch the list of all images for that title.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/titles/45606/images

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/titles/45606/images

<?xml version="1.0" encoding="UTF-8"?>
<images type="array">
  <image>
    <id type="integer">1</id>
    <external_id>ABCD9982</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
    <type>Poster</type>
    <file-name>movie.jpg</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1238791dhskajhfskajsfh</file-md5>
    <is-cover type="boolean">false</is-cover>
    <link rel="self" href="https://movida.bebanjo.net/api/images/1"/>
    <link rel="file" href="https://movida-s3.amazonaws.com/images/attachments/1/original/1544708998-07fa9afd4df01b0ad85193be47c012526cc85c28.jpg"/>
    <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
  </image>
  <image>
    <id type="integer">7</id>
    <external_id>ABCD9983</external_id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
    <type>BoxCover</type>
    <file-name>dvd_cover.jpg</file-name>
    <file-size type="integer">234556943</file-size>
    <file-md5>1238791dhskajhfskajsft</file-md5>
    <is-cover type="boolean">true</is-cover>
    <link rel="self" href="https://movida.bebanjo.net/api/images/7"/>
    <link rel="file" href="https://movida-s3.amazonaws.com/images/attachments/7/original/1544708999-a4daa042b26489e0b085483e38e677d0a12eba61.jpg"/>
    <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
    <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/7/target_platforms"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/images/7/metadata"/>
  </image>
</images>

{
  "entries": [
    {
      "resource_type": "image",
      "id": 1,
      "external_id": "ABCD9982",
      "width": 1280,
      "height": 720,
      "encoding": "jpeg",
      "aspect_ratio": "16:9",
      "type": "Poster",
      "file_name": "movie.jpg",
      "file_size": 2345569434,
      "file_md5": "1238791dhskajhfskajsfh",
      "is_cover": false,
      "self_link": "https://movida.bebanjo.net/api/images/1",
      "file_link": "https://movida-s3.amazonaws.com/images/attachments/1/original/1544708998-07fa9afd4df01b0ad85193be47c012526cc85c28.jpg",
      "content_link": "https://movida.bebanjo.net/api/titles/45606",
      "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
      "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
    },
    {
      "resource_type": "image",
      "id": 7,
      "external_id": "ABCD9983",
      "width": 1280,
      "height": 720,
      "encoding": "jpeg",
      "aspect_ratio": "16:9",
      "type": "BoxCover",
      "file_name": "dvd_cover.jpg",
      "file_size": 234556943,
      "file_md5": "1238791dhskajhfskajsft",
      "is_cover": true,
      "self_link": "https://movida.bebanjo.net/api/images/7",
      "file_link": "https://movida-s3.amazonaws.com/images/attachments/7/original/1544708999-a4daa042b26489e0b085483e38e677d0a12eba61.jpg",
      "content_link": "https://movida.bebanjo.net/api/titles/45606",
      "target_platforms_link": "https://movida.bebanjo.net/api/images/7/target_platforms",
      "metadata_link": "https://movida.bebanjo.net/api/images/7/metadata"
    }
  ]
}

Creating images for a title

To create images, you just need to POST a proper XML/JSON image representation (similar to the ones you get when fetching an image) to the images URL resource of a title. That URL can be found in a link which rel attribute equals ‘images’. The only required attribute is the encoding, the rest are optional.

If needed, the image file for an Image resource can be provided via the attachment parameter which is intended to be set with the Base64 representation of such image file. Heads up, this will increase the size of the payload to be sent to the server so this will also make the request slower. Therefore, it’s a good practice to try to keep the size of the images as small as possible. On the other hand, if you are planning to create lots of big images in a short period of time, you must consider using external URLs, which is described next, as it will probably fit your needs better.

For example, this POST would create an image (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat image.xml

$ cat image.json

<image>
  <encoding>jpeg</encoding>
  <attachment>data:image/jpeg;base64,iVB…QmCC</attachment>
</image>

{
  "encoding": "jpeg",
  "attachment": "data:image/jpeg;base64,iVB…QmCC"
}

Please, in the previous example keep attention to the value expected for <attachment> node, where image/jpeg represents the mime type of the base64 encoded image. Generally speaking, the expected value for <attachment> will be data:$mime_type;base64,$base64_string, where $mime_type and $base64_string will be specific for the uploaded image.

When the image file is provided through the <attachment> parameter, no image file name is set by default, so you will probably want to give <file-name> optional parameter a proper value.

<image>
  <encoding>jpeg</encoding>
  <file-name>dvd_cover.jpg</file-name>
  <attachment>data:image/jpeg;base64,iVB…QmCC</attachment>
</image>

{
  "encoding": "jpeg",
  "file_name": "dvd_cover.jpg",
  "attachment": "data:image/jpeg;base64,iVB…QmCC"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @image.xml "https://movida.bebanjo.net/api/titles/45606/images"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @image.json "https://movida.bebanjo.net/api/titles/45606/images"

Mediagenix On-Demand will return the full XML/JSON of the image just created:

<?xml version="1.0" encoding="UTF-8"?>
<image>
  <id type="integer">99</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>jpeg</encoding>
  <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
  <type nil="true"></type>
  <file-name>dvd_cover.jpg</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1238791dhskajhfskajsfh</file-md5>
  <is-cover type="boolean">false</is-cover>
  <link rel="self" href="https://movida.bebanjo.net/api/images/99"/>
  <link rel="file" href="https://movida-cloud-image-storage.com/images/923478653-9843465.jpg"/>
  <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
</image>

{
  "resource_type": "image",
  "id": 99,
  "external_id": "ABCD9982",
  "width": 1280,
  "height": 720,
  "encoding": "jpeg",
  "aspect_ratio": "16:9",
  "type": null,
  "file_name": "dvd_cover.jpg",
  "file_size": 2345569434,
  "file_md5": "1238791dhskajhfskajsfh",
  "is_cover": false,
  "self_link": "https://movida.bebanjo.net/api/images/99",
  "file_link": "https://movida-cloud-image-storage.com/images/923478653-9843465.jpg",
  "content_link": "https://movida.bebanjo.net/api/titles/45606",
  "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
  "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
}

Creating images providing an external URL

There’s another way to create images, by providing an external URL to an existing image in the file-url parameter. See the above payload as an example:

$ cat image.xml

$ cat image.json

<image>
  <encoding>jpg</encoding>
  <file-url>https://external-domain.com/836f80e394fbe24348ace81.jpg</file-url>
</image>

{
  "encoding": "jpg",
  "file_url": "https://external-domain.com/836f80e394fbe24348ace81.jpg"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @image.xml "https://movida.bebanjo.net/api/titles/45606/images"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @image.json "https://movida.bebanjo.net/api/titles/45606/images"

Mediagenix On-Demand will return the full XML/JSON of the image just created:

<?xml version="1.0" encoding="UTF-8"?>
<image>
  <id type="integer">99</id>
  <external_id>ABCD9982</external_id>
  <width nil="true"/>
  <height nil="true"/>
  <encoding>jpg</encoding>
  <aspect-ratio nil="true"/>
  <type nil="true"/>
  <file-name nil="true"/>
  <file-size nil="true"/>
  <file-md5 nil="true"/>
  <is-cover type="boolean">false</is-cover>
  <link rel="self" href="https://movida.bebanjo.net/api/images/99"/>
  <link rel="file" href="https://external-domain.com/836f80e394fbe24348ace81.jpg"/>
  <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/99/target_platforms"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/images/99/metadata"/>
</image>

{
  "resource_type": "image",
  "id": 99,
  "external_id": "ABCD9982",
  "width": null,
  "height": null,
  "encoding": "jpg",
  "aspect_ratio": null,
  "type": null,
  "file_name": null,
  "file_size": null,
  "file_md5": null,
  "is_cover": false,
  "self_link": "https://movida.bebanjo.net/api/images/99",
  "file_link": "https://external-domain.com/836f80e394fbe24348ace81.jpg",
  "content_link": "https://movida.bebanjo.net/api/titles/45606",
  "target_platforms_link": "https://movida.bebanjo.net/api/images/99/target_platforms",
  "metadata_link": "https://movida.bebanjo.net/api/images/99/metadata"
}

Asynchronously, Mediagenix On-Demand will be retrieve the image and its attributes, such as dimensions or MD5 and will update the existing resource with these information (some of the values provided in the creation will be updated).

Eventually, when it finishes most of the attributes of the image will have been overwritten by Mediagenix On-Demand, with the values corresponding to the provided image:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/images/99

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/images/99

<?xml version="1.0" encoding="UTF-8"?>
<image>
  <id type="integer">99</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">800</width>
  <height type="integer">600</height>
  <encoding>jpg</encoding>
  <aspect-ratio type="AspectRatio">4:3</aspect-ratio>
  <type></type>
  <file-name>836f80e394fbe24348ace81.jpg</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1238791dhskajhfskajsfh</file-md5>
  <is-cover type="boolean">false</is-cover>
  <link rel="self" href="https://movida.bebanjo.net/api/images/99"/>
  <link rel="file" href="https://movida-cloud-image-storage.com/images/343421421-as21232.jpg"/>
  <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/99/target_platforms"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/images/99/metadata"/>
</image>

{
  "resource_type": "image",
  "id": 99,
  "external_id": "ABCD9982",
  "width": 800,
  "height": 600,
  "encoding": "jpg",
  "aspect_ratio": "4:3",
  "type": null,
  "file_name": "836f80e394fbe24348ace81.jpg",
  "file_size": 2345569434,
  "file_md5": "1238791dhskajhfskajsfh",
  "is_cover": false,
  "self_link": "https://movida.bebanjo.net/api/images/99",
  "file_link": "https://movida-cloud-image-storage.com/images/343421421-as21232.jpg",
  "content_link": "https://movida.bebanjo.net/api/titles/45606",
  "target_platforms_link": "https://movida.bebanjo.net/api/images/99/target_platforms",
  "metadata_link": "https://movida.bebanjo.net/api/images/99/metadata"
}

The only way to check if an image has been fetched and its attributes have been updated is by comparing the value of the attribute link[rel=file] with the original value provided in the creation request.

Poster images for the catalogue

After an image is uploaded, Mediagenix On-Demand checks whether it is suitable to be used as a Poster in the Catalogue for the Title, Title Group, Brand it was associated with. The image will be used as a Poster if:

  • the parent Title, Title Group or Brand doesn’t already have a Poster
  • the aspect ratio is 2:3 or 3:4

You can also explicitly tell Mediagenix On-Demand to use the image as a Poster for the associated content by setting the attribute is-cover in your API request:

<image>
  ...
  <is-cover type="boolean">true</is-cover>
  ...
</image>

{
  "resource_type": "image",
  // ...
  "is_cover": true,
  // ...
}

Updating images of a title

You can update images issuing a PUT request to the URL of a given image, as the following example illustrates. This example only updates the image’s type, name, URL and dimensions.

$ cat image.xml

$ cat image.json

<image>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</width>
  <type>Thumbnail</type>
  <file-url>https://wadus.com/movie.jpg</file-url>
  <file-name>movie.jpg</file-name>
  <is-cover type="boolean">false</is-cover>
</image>

{
  "external_id": "ABCD9982",
  "width": 1280,
  "height": 720,
  "type": "Thumbnail",
  "file_url": "https://wadus.com/movie.jpg",
  "file_name": "movie.jpg",
  "is_cover": false
}

Now we send the XML/JSON as the body of a PUT request to the image’s URL

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @image.xml "https://movida.bebanjo.net/api/images/1"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @image.json "https://movida.bebanjo.net/api/images/1"

The PUT request would return the updated XML/JSON of the image:

<image>
  <id type="integer">1</id>
  <external_id>ABCD9982</external_id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>jpeg</encoding>
  <aspect-ratio type="AspectRatio">16:9</aspect-ratio>
  <type>Thumbnail</type>
  <file-name>movie.jpg</file-name>
  <file-size nil="true"></file-size>
  <file-md5 nil="true"></file-md5>
  <is-cover type="boolean">false</is-cover>
  <link rel="self" href="https://movida.bebanjo.net/api/images/1"/>
  <link rel="file" href="https://wadus.com/movie.jpg"/>
  <link rel="content" href="https://movida.bebanjo.net/api/titles/45606"/>
  <link rel="target_platforms" href="https://movida.bebanjo.net/api/images/1/target_platforms"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/images/1/metadata"/>
</image>

{
  "resource_type": "image",
  "id": 1,
  "external_id": "ABCD9982",
  "width": 1280,
  "height": 720,
  "encoding": "jpeg",
  "aspect_ratio": "16:9",
  "type": "Thumbnail",
  "file_name": "movie.jpg",
  "file_size": true,
  "file_md5": true,
  "is_cover": false,
  "self_link": "https://movida.bebanjo.net/api/images/1",
  "file_link": "https://wadus.com/movie.jpg",
  "content_link": "https://movida.bebanjo.net/api/titles/45606",
  "target_platforms_link": "https://movida.bebanjo.net/api/images/1/target_platforms",
  "metadata_link": "https://movida.bebanjo.net/api/images/1/metadata"
}

Notice that the attribute link[rel=file] can’t be updated.

Delete an image of a title

The following example shows how to destroy a particular image. Only a DELETE HTTP request to its URL is required:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/images/1"

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/images/1"

The DELETE request doesn’t return anything, as that image is now gone.

Deleting an image won’t have any side-effect on linked resources such as the title or the series.

File Name Validation

Note that the Mediagenix On-Demand API validates the file name for image files. If the file name in a given request includes one or more restricted characters, then the response body for the 4xx error will include the “The request could not be processed by the server due to malformed syntax” message. Please review the Status Codes and Errors page for the full list of restricted characters and associated HTTP status codes.