Manuals

UserMedia API Manual

Icecat users have the ability to upload media assets to Icecat endpoints using the UserMedia feature. This manual provides instructions on uploading videos via the UserMedia API and presenting them via Icecat LIVE.

Swagger schema: https://api.icecat.biz/#/UserMedia

1. Initial Setup

All requests are sent to https://bo.icecat.biz/restful/v3/ and SessionType is always Rest.While it is possible to reach API with your programming language or terminal tools like curl and wGet, I would recommend using tools like Insomnia or Postman to work with our data as the requests can be complicated.

2. Authorization

You need to have either a brand or shop type account to use UserMedia API. To initiate data transmission, you must authenticate yourself with the API by obtaining a session key. This session key is required for subsequent requests to ensure proper API authentication. Please, follow point 1.3 from the PUSH API manual.

3. UserMedia API Endpoints

3.1. POST – Add UserMedia Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Headers:

Content-Type: multipart/form-data

Multipart data:

'Title=My Title'
'LanguageIds=10,1,2'
SourceLink=http://example.com/FunnyElephant.mp4
ProviderUserId=99999

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: multipart/form-data' \
  --header 'accept: application/json' \
  --form 'Title=My Title' \
  --form 'LanguageIds=10,1,2' \
  --form SourceLink=http://example.com/FunnyElephant.mp4 \
  --form ProviderUserId=99999

Variables:

_.accessKey Access key
TitleVideo title
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
SourceLinkLink to your video. Allowed formats: 3gp, avi, flv, m4v, mkv, mov, mp4, mpg, ogg, vob, wmv, webm.
ProviderUserIdID of your Icecat account, contact support@icecat.biz to get yours.

Success response 201:

{
    "Data": {
     "VideoId": 33232080
    }
}

3.2. GET – Receive Video Data by VideoId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
  "Data": {
 "VideoId": 99999,
 "Title": "My Title",
 "Link": "https://example.icecat.biz//",
 "LanguageIds": [
   2,
   3,
   10
 ],
 "ProviderUserId": 303033,
 "Status": "Done",
 "PreviewImageLink": "https://example.icecat.biz//",
 "PreviewImageLinkTmp": "https://example.icecat.biz//",
 "PreviewThumbLink": "https://example.icecat.biz//",
 "PreviewThumbLinkTmp": "https://example.icecat.biz//",
 "Accesses": [],
 "AgeRatings": []
  }
}

Response is constructed from links to your UserMedia on Icecat servers and additional data.

VideoIdVideo ID
TitleVideo title
LinkLink to the video
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
ProviderUserIdVideo owner’s ID
StatusVideo upload status
PreviewImageLinkLink to video image preview
PreviewImageLinkTmpTemporary link to video image preview
PreviewThumbLinkLink to video image preview in thumbnail format
PreviewThumbLinkTmpTemporary link to video image preview in thumbnail format
AccessesUsers are allowed to update your video
AgeRatingsAge Ratings activated for your videos

3.3. PATCH – Update Title for Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&Sess
ionType=Rest

Body:

{
    "Title": "My new Title"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
 "Title": "My new title"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
    "Data": {}
}

3.4. DELETE – Delete Video By ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200: Returns an ID of the deleted Video.

{
    "Data": {
     "VideoId": 332079
    }
}

3.5. GET – Receive all UserMedia Videos

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key

Success response 200: Method returns all Videos stored on Icecat.

4. Languages

Please check the IDs for Icecat Languages here: Locales & Language Code

4.1. POST – Add language to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "LanguageId": 3
}'

Body:

{
  "LanguageId": 3
}

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200: Returns ID of activated languages.

{
    "Data": {
     "LanguageId": 3
    }
}

4.2. GET – Receive Video Data with Language by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Success response 200:

{
    "Data": {
     "VideoId": 0,
     "Title": "",
     "Link": "",
     "LanguageIds": [
      2,
      3,
      10
     ],
     "ProviderUserId": 0,
     "Status": "Done",
     "PreviewImageLink": "",
     "PreviewImageLinkTmp": "",
     "PreviewThumbLink": "",
     "PreviewThumbLinkTmp": "",
     "Accesses": [],
     "AgeRatings": []
    },
    "Metadata": {
     "Languages": [
      {
       "LanguageId": 2,
       "ShortCode": "NL"
      },
      {
       "LanguageId": 3,
       "ShortCode": "FR"
      },
      {
       "LanguageId": 10,
       "ShortCode": "BR"
      }
     ]
    }
}

4.3. DELETE – Remove Language from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideoID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200:

{
    "Data": {}
}

5. Accesses

With accesses you can assign users to edit your UserMedia. You can only allow shop users to get access to your videos.

5.1. POST – Add an access for Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/332080/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest' \
  --data '{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.userIDID of a shop user you would like to grant access to. Please contact support@icecat.biz.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 201:

{
    "Data": {
     "AccessId": 0,
     "AuthorizedUserId": 0,
     "UserReference": "My-team-lead"
    }
}

5.2. PATCH – Update UserReference by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
    "UserReference": "My-ex-team-lead"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{ _.accessId }}?AccessKey={{ _.accessKey }}&SessionType=Rest' \
 --data '{
 "UserReference": "My-ex-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 200:

{
    "Data": {
     "AccessId": 9060198,
     "AuthorizedUserId": 110865,
     "UserReference": "My-ex-team-lead"
    }
}

5.3. DELETE – Remove Access by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.

Success response 200:

{
    "Data": {}
}

6. Age Ratings

Age Ratings are additional labels to mark which audience the video is available for. They display minimum age requirements for the content.

6.1. GET – Receive Age Ratings Dictionary

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Response returns all information about each Age Rating provider.

AgeRatingIdID of the Age Rating provider.
AgeRatingAge Rating provider name.
AgeRatingValuesEach provider has its own system of ratings and this array contains all possible values.
AgeRatingDescriptorsDescription of content that appears in video which can affect Age Rating.

6.2. POST – Add Age Rating to Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
 2
  ]
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data ' {
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
    2
  ]
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
AgeRatingId, AgeRatingValueId, AgeRatingDescriptorIdsRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
     "AgeRatingId": 1
    }
}

6.3. PATCH – Update AgeRatingValue by AgeRatingId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingValueId": 3
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
  "AgeRatingValueId": 3
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingValueIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response:

{
    "Data": {}
}

6.4. DELETE – Remove Age Rating from video by ID

Path: 

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

7. Age Ratings Descriptors

AgeRatingDescriptor is a label that shows additional information about provocative content that is not suited for minors. For example, “Drugs” or “Sex” are the descriptors in PEGI rating.

7.1. POST – Add Age Rating Descriptor to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingDescriptorId": 7
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "AgeRatingDescriptorId": 7
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingDescriptorIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
     "AgeRatingDescriptorId": 7
    }
}

7.2. DELETE – Remove Age Descriptor from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, _.ageRatingDescriptorIDRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

8. Errors

Error codeError messageResolution
400Some of the parameters are not valid or were not inputted. See returned message for detailsCheck your input method.
400HTTP method GET is not described in the swagger schema.Change HTTP method to HTTPS.
401Your AccessKey is not valid any moreRenew your AccessKey with Session/ endpoint.
403You are not assigned to this content!Check the Video accesses with UserMedia/Videos/{{_.videoID}} endpoint.
500This should never happen!Report such cases to support@icecat.biz

9. UserMedia API with Icecat LIVE JS AP

To retrieve videos uploaded through the UserMedia API using Icecat LIVE JS API, you will need to include two essential parameters in your request code:

UserReferenceUser references code. This is a user identifier that helps to search loaded video into the Icecat system.
ProviderIdUser identifier of the owner of an uploaded video in Icecat system (the same as ProviderUserId).

These two parameters are required for showing the user’s videos into live html.

Age gating is activated by default, however it is possible to disable it by adding videoAgeGatingDisabled: true parameter. Please see an example below.

9.1. Granular call + UserMedia

Videos uploaded via UserMedia API can be requested via Granular call to be included among other containers. For this you need to include a ‘videos’ container to the call, UserReference and ProviderId are also required. The request works with any identifier combinations, Smart call and Multilingual request. Please refer to the Granular Call manual for more info.

Granular call with UserMedia API parameters – Brand + MPN:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

The same request with Age gating disabled:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
  videoAgeGatingDisabled: true,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

9.2. Icecat Live API for Granular call of UserMedia API with only media assets

Users can request videos uploaded via UserMedia API exclusively without requesting any specific product or data containers using Icecat Live. ProviderId and UserReference parameters are required.

<!DOCTYPE html>
<html>

<head></head>

<body>
  <div id="сontainer"></div>
  <script>
 window.addEventListener('liveload', function () {
   IcecatLive.getUnlinkedVideos(
     '#сontainer',
     {
       shopname: 'shop_user',
       UserReference: 'user_code',
       ProviderId: 1,
     },
     'en'
   );
 });
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
</body>

</html>

9.3. Icecat Live API for Regular call of UserMedia API

The Regular call of datasheet + UserMedia API parameters – Brand + MPN (can also be used with Icecat ID based, EAN-based calls, and Smart call):

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="container"></div>
    <script>
      window.addEventListener('liveload', function () {
        window.IcecatLive.getDatasheet(
          '#container',
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

Read further: Manuals, , , ,

icecat

Share
Published by
icecat
Tags: IcecatmanualPIMproduct content
10 months ago

Recent Posts

Intos Electronic AG Joins Open Icecat with Their Own Brand InLine: High-Quality Product Content Now Easily Available

Established in 1991 and based in Gießen, Germany, Intos Electronic AG has built a reputation…

13 hours ago

UN: E-commerce is Nowhere as Established as in the Netherlands

In a recent report from the United Nations Conference on Trade and Development (UNCTAD), the…

2 days ago

HATOR Gaming Becomes an Open Icecat Sponsor

HATOR Gaming is a prominent gaming hardware brand known for its innovative and high-quality products…

3 days ago

Icecat Ranked 12th in Main Software Top 50 2024 Edition

Icecat secured the 12th position in the Main Software 2024 edition with an impressive score…

4 days ago

Nordic Marketplace CDON uses Icecat Product Content to Enhance Online Experience

CDON, based in Sweden, is one of the Nordics' leading and biggest marketplaces. On the…

1 week ago

Icecat Featured in BDO’s 2024 Digital Agencies Market Report

Icecat was featured in the 2024 BDO Digital Agencies Market Research report. This recognition highlights…

1 week ago