In my previous post, we delved into Content Hub ONE, exploring its product overview and the initial steps to kickstart the development journey. Today, I am diving into the Media Upload API. However, that's not all, I'm also excited to introduce you to Sitecore Connect and add an extra touch of excitement by harnessing the power of OpenAI's Dall-e service to generate images using AI.
Sitecore Connect
Sitecore Connect, is a Low-code/No-code integration platform powered by Workato. This platform empowers you to effortlessly connect your Sitecore products with the rest of your tech stack, opening up endless possibilities. This article won't delve into the nitty-gritty of getting started with Sitecore Connect, so If you're new to this product and seeking a solid understanding or looking for a comprehensive guide, I highly recommend checking out the Sitecore Connect for Beginners series by my friend Nikola.
Nikola's series will provide you with a fantastic foundation, allowing you to harness the full potential of Sitecore Connect in your projects. So, without further ado, let's dive into the realms of the Media Upload API and the capabilities of AI-generated images through OpenAI's Dall-e service.
OpenAI - DALL·E 2 Service
DALL·E 2 is an AI system that can create realistic images and art from a description in natural language. We can interact with the API through HTTP requests, and Sitecore Connect already provides an App to make the connection easier.
Content Hub ONE - Media Upload API
The Media Upload API allows us to upload media items and make those available in ContentHub ONE to then use in our content items.
Upload steps
To upload media assets, we basically need to follow those four steps:
- Generate upload links either one at a time or in bulk.
- Use each link to upload the corresponding asset.
- Use the fileId of each asset to complete the upload.
- Use the fileId of each asset to make it available as a media item.
It's important to know the data model for media items
Field Type | Description | Required | Limitation |
ID | Unique identifier for the media item. It must be alphanumeric and can contain periods, underscores, and hyphens, but not spaces or other special characters.By default, the identifier is the same as the name. Once defined it cannot be changed. | Yes | 256 Characters |
Name | Name of the media item. It can contain periods but cannot contain spaces or special characters. | Yes | 1000 Characters |
Description | Description of the media item. | No | 50000 Characters |
File | File object. | N/A | 70 MB |
System | List of system properties for a media item. | N/A | N/A |
Cooking time, let's define the recipes
In this particular example, our goal is to create a recipe within Sitecore Connect that actively listens to a webhook. By sending a text as a parameter, we can leverage the power of OpenAI to generate a corresponding image. Then, we'll seamlessly proceed with the media upload steps, ensuring the image is readily available in Content Hub ONE for editors to utilize. The best part? This entire process can be accomplished without writing a single line of code! Get ready to witness the seamless integration of cutting-edge technologies, enabling effortless image generation and deployment within Content Hub ONE.
Generate and upload media item recipe
We create our first recipe by choosing "Trigger from a webhook" as starting point.
We set up the webhook by giving it a name and adding a string parameter (ImagePrompt) as mandatory
Please note that we can trigger our webhook from the following URL: https://webhooks.eu.workato.com/webhooks/rest/1e4aafbe-b852-4c95-8f09-788971aab0d8/generate-image-and-upload
Even though the ImagePrompt parameter is set as mandatory, I'll also add an if condition to stop the flow in the case is missing in the request:
For the next action, we choose "Action in App" and browse for the existing connectors, choose OpenAI, and then the "Generate Image" action. Follow the wizard to set it up (API Client Key/secret).
We configure the "Generate Image" action to take the "ImagePrompt" parameter as input:
We add another validation to make sure the API call generated the image successfully and gave back the generated image URL
Next action, we select "Action in an App" and we start setting up our next recipe. Our second recipe is going to expect three params ("Asset URL", "Asset Name" and "Asset Description").
Please note that I've used the formula for the Asset Name field so it's compliant with name field restrictions (check table).
Adding error handling, this is how our recipe looks like:
The Upload Media Asset recipe
In this case, we create the recipe using the "Build recipe function" as starting point.
We add three fields as parameters ("Asset URL", "Asset Name" and "Asset Description") as strings, and "Result" (int) and "ErrorMessage" as return values.
The next action is to generate the link by making a call to Content Hub Upload Media API, as we described in the previous section. First, we add validation for the parameters and next, we add error handling, now we are ready to create our action "Action in an App" and search for Content Hub ONE.
We can now connect to it by giving the API key and values:
Remember you can get all this information from the OAuth client section in the Content Hub ONE dashboard
Generating an upload link (single asset)
We create our "Generate Upload Link" action and give the following values:
- Method: POST
- Path: https://mms-upload.sitecorecloud.io/api/media/v1/upload/link/generate
- Headers
- x-mms-content-type: image/jpeg (Content Hub ONE supports
image/gif,image/jpeg,image/jpg,image/png, andimage/webp.) - x-mms-content-length: 13213
- Content-Type: application/json
Input: filename
Response:
- Link (string)
- fileId (string)
We add validation for the returned fields ("Link" and "File ID") and error handling (Monitor). Now is the time to add an action to make an HTTP call to the URL generated from OpenAI (parameter) to download the asset we will be uploading to Content Hub ONE.
Make sure you set the "Asset URL" parameter as the request URL and "Binary" as the response type. In that case, the method is "GET".
Upload the asset
This method uploads an asset using the generated upload link. Since the API call to upload the asset doesn't need authentication, I'll just use again an HTTP call.
- Method: PUT
- Request URL: Link from the previous step
- Request content type: Binary
- Request Body: Body from the previous step
- Headers
- Application: application/json
- Content-Type: application/json
Now, we add an if condition to make sure the previous call returned an HTTP code = 201.
The Complete upload action
This method is to complete the upload of an asset using its fileId, which was obtained when the link was generated.
- Method: POST
- Path: https://mms-upload.sitecorecloud.io/api/media/v1/upload/link/complete
- Request Param: File ID from the previous step
- Headers
- x-mms-content-length: 13223
- x-mms-content-type: image/jpeg
- Content-Type: application/json
Create a media item
This is the last method in the flow and is to generate a media item based on an asset, according to the asset's fileId. Each media item must be given a name, and it can also be given a description if needed.
For this we create our last ContentHub App action with the following settings
- Method: POST
- Path: https://content-api.sitecorecloud.io/api/content/v1/media
- Input
- ID
- Name
- Description
- File ID
Headers
- Content-Type: Application/json
- Accept: text/plain
The complete recipe
This is what the complete recipe looks like:
Time to test it!
We are all set, now is the time to give it a try! We can just trigger the webhook by hitting the webhook URL, just need to pass the ImageCaption query string. Click on the "Start recipe" button for both of the recipes we created.
Webhook URL example: https://webhooks.eu.workato.com/webhooks/rest/1e4aafbe-b852-4c95-8f09-788971aab0d8/generate-image-and-upload?ImagePrompt=a happy cat wearing an Argentinian football jersey
We can confirm that the recipes have been completed, so we are ready to log into Content Hub ONE and check our newly updated asset in the media section:
Our happy Argentinian cat (with a really weird jersey btw) is there and ready to be used by content authors. Let's give it a last try by calling the same webhook trigger with ImagePrompt parameter "A dog wearing sunglasses", and check the result in Content Hub ONE:
And just for fun, a last one, let's see what OpenAI does with it Image Prompt: "a smart guy wearing a shirt with the Sitecore logo":
Well.. quite close, isn't it?
Conclusion
The core objective of this article is to explore the inner workings of the Upload Media API while simultaneously introducing the capabilities of Sitecore Connect. By doing so, I aim to demonstrate how we can achieve great results and establish seamless connections between Sitecore products and third-party integrations, all without the need to write a single line of code.
References
- Content Hub ONE API Video series from Sebastian Winter: https://www.youtube.com/watch?v=qxXTiVd8rZ8
- Official Content Hub ONE API documentation: https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api--media-items.html
- Sitecore Connect series from Nikola Gotsev: https://sitecorecorner.com/2023/05/01/sitecore-connect-for-begginers-part-1-what-is-sitecore-connect-and-basic-building-blocks/
- Official Sitecore Connect documentation: https://doc.sitecore.com/connect/en/users/sitecore-connect/introduction-to-sitecore-connect.html
