Overview

In the Vidizmo Portal, you can easily upload various file formats, from audios to documents. This article focuses on uploading audio file and creating mashup with it seamlessly. The API for audio file uploads transfers content to your storage. The audio file upload process involves three steps: initialization, chunk uploads, and commitment, making it efficient for large files. Additionally, you can create new or existing mashups using the Create Mashup API within the Vidizmo Portal. During testing, we used Postman to validate the audio file upload and create mashup process.


Below is visual representation of the process of uploading an Audio file to the Vidizmo portal using the three API calls: initialize, upload chunks, commit.

Before You Start

  • Authorize yourself in the portal by using the following endpoint:/api/v1/user/authenticate/. To learn how to achieve authorization, refer to the User Authentication Guide. 
  • Once you have obtained the authorization token, you can proceed to upload file and create a mashup in the portal.
  • Prepare a reliable testing platform, such as Postman, to test the APIs effectively. 


Upload Audio File - Initialize

The initialization step initiates the upload process for an audio file. It provides a foundation for the secure and efficient transfer of audio content.

 

Initialization Request 

To initialize the upload of an audio file, follow these details: 

1. Make PUT request to the following endpoint: 


{{Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}}  

With the query parameters: comp = initialize to indicate the initialization step. 

So now, the endpoint will become: 


{{Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}}?comp=initialize
Here:
  • {{Domain}}: Your tenant URL. 
  • {{blobid}}: An identifier for the blob or upload session. 
  • {{fileName}}: The name of the file you are uploading. 
  • {{fileGuid}}: A unique identifier for the file. 

For comprehensive information about the api and query parameters, refer to: Upload File Documentation


2. Request Details:

  • Request Header: 
    Content-Type: application/json 
  • Authorization:  
Bearer-Token: {{Token}}, here the token is the one you receive while you authenticate yourself in the portal. 

 

3. Response Details  

Upon successful initiation of the upload, the API responds with a status code of 202 Accepted. This status code indicates that the initialization has been accepted, and the upload process is underway.  


Next Steps 

After successful initialization, proceed with the next steps of the audio file upload process, which includes uploading file chunks and committing the upload which are discussed in the following sections.  

 

Upload Audio File – Upload Chunks

After initialization, the audio file is broken into smaller "chunks". These chunks are typically of a specified size. 

The user then sequentially uploads each chunk to the server or API. It sends these chunks one by one, ensuring that they are received and stored on the server. Uploading in smaller chunks allows for better resiliency against network interruptions or failures. If a chunk fails to upload, only that chunk needs to be retransmitted, not the entire file. 

 

Here’s how you can upload chunks of your audio file: 


Upload Request 

To upload an audio file block, follow these details: 


1. Make a PUT request to the following endpoint: 

{{Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}} 


With the Query Parameters: 

  • Comp = block: Specifies that this is a block upload. 
  • Blockid = 1: Indicates the order of the block within the file. In this case, block number 1.   

So, now the endpoint becomes:  

{{Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}}?comp=block&blockid=1


2. Request Details: 

  • Request Body: Binary data containing the Audio file block. 
  • Request Header: 

Content-Type: application/json 

  • Authentication: 
Bearer Token: {{token}} (your authentication token)

 

3. Response Details:

Upon successfully uploading an audio file block, the API responds with the following information: 


Example - Response Body (JSON)

{
  "byteUploaded": 103016,
  "eTag": "1",
  "chunkNumber": 1
}

Here: 

  • byteUploaded: The number of bytes uploaded in the block. 
  • eTag: An entity tag or version identifier for the block. 
  • chunkNumber: The number of the block being uploaded (in this case, block number 1). 


Note: In the case of our short audio file, it was efficiently uploaded using a single chunk. However, it's essential to note that if you are dealing with a larger audio file, the upload process may involve multiple chunks. 


Next Steps 

Repeat this block upload process for each block of the audio file until all blocks have been successfully uploaded and then move on to the next step of sending a commit request. 


Upload Audio File – Commit

Once all the chunks have been successfully uploaded, the user sends a commit request. This request informs the server that all the chunks are in place and should be assembled into the final file. Here’s how you can do that:

 

1. Make a PUT request to the following endpoint: 

{{Your-Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}}
With Query Parameters: 
  • Comp = blocklist, Indicates that this is a blocklist commit. 
  • CaptureMediaInformation = true, When set true it means requesting to capture media information 
So, now the endpoint should look like this: 

{{Domain}}/api/v1/blob/{{blobid}}/{{fileName}}/{{fileGuid}}?comp=blocklist&captureMediaInformation=true 

2. Request Details 

  •  Example - Request Body (JSON):
 The response received from Upload Chunks call will be in the request body of commit call:
[
  {
    "eTag": "1",
    "chunkNumber": 1
  }
]

  • Authorization: 
Bearer token: {{token}} (your authentication token) 


3. Response Details 

Upon successfully committing the upload file, you will receive a URL of source content as a response which will be useful while creating a Mashup. 


Example - Response Body (JSON)

{
  "playbackURL": "https://example.com/playback/audio.mp3",
  "downloadURL": "https://example.com/download/audio.mp3"
}

Next Steps 

Once all three API calls were successfully executed, now you can easily create mashup with it. In the next section we will be explaining how we can utilize the URL of source content received in to creating a mashup.


Create Mashup 

Once we uploaded an audio file successfully, we can also create a mashup with it. The Create Mashup API allows us to create new or existing mashups in the Vidizmo portal. This API request will create a mashup that contains the specified media items. To create a mashup in Vidizmo, follow these steps: 


1. Make a POST request

Make a POST request to the following endpoint to create a mashup:  

The payload of this Api is quite large. To reduce the challenges posed by handling such large payloads, the Mashup API. offer a flexible solution: Users can define a set of query parameters within their API requests to specify which properties of the mashup they intend to update. By doing so, you can minimize the payload size, transmitting only the essential data required for making the request. 


Example - Query Parameters: 

{{Domain}}/api/v1/mashup?mashupParts=BasicInfo&mashupParts=Content 

Note: In the query parameters, we have deliberately included the Basic Information, Player, and Content parameters. The reason behind this is our intention to facilitate updates to these specific parameters. Depending on your specific requirements, you have the flexibility to add or omit additional parameters in the Mashup Parts as needed. 

Whether you require more parameters for comprehensive mashup details or fewer to keep it minimal, you can adjust the request accordingly. 

 

2. Request Details: 

  • Request Headers: 

Content-Type: application/json 

  • Authentication: 

Bearer-Token: {{Token}}, here the token is the one you receive while you authenticate yourself in the portal. 

  • Request Body: 

The payload required, considering the query parameters we are inputting is: 


Example - Request Body (JSON)

{
    "format": "Audio", //Type of mashup file 
    "defaultViewingAccess": "Anonymous",
    "tenant": {
        "id": "{{tenantId}}" //Tenant to which campaign belongs 
    },
    "title": "{{mashupTitle}}", //Unique title of the mashup 
    "category": "{{category}}",
    "categoryid": "{{categoryId}}", //Unique identifier for the category 
    "name": "{{categoryName}}" //Unique name for the category 
},
"content": [
    {
        "fileName": "{{fileGuid}}", //Unique file Globally Unique Identifier 
        "contentStorageId": "{{contentStorageId}}", //Unique integer identifier for content storage 
        "contentFormatId": 5,
        "contentType": "Audio",
        "contentStatus": "All",
        "contentDetails": {
            "contentFiles": [
                {
                    "fileSize": 103016,
                    "contentFileAttributes": [
                        {
                            "name": "Quality",
                            "value": "Original"
                        }
                    ],
                    "streamType": "None",
                    "playbackURL": "{{playbackURL}}", //URL used to stream content directly in a web browser or media player 
                    "downloadURL": "{{downloadURL}}" //URL is used to initiate the download of a file from a web server. 
                }
            ]
        }
    }
],
"thumbnails": [] 
    "player": {
    "playerTemplateDetail": {
        "playbackBehaviour": {
            "preserveUserSettings": true,
            "autoPlay": true,
            "autoAdvance": false,
            "loop": false,
            "lowbandwidthInitialize": false,
            "muted": false,
            "allowSeekForward": true,
            "allowSeekBackward": true,
            "playOriginal": true
        }
    }
},
"uuid": "{{mashupUUID}}" //Universally Unique Identifier of mashup Object. 
}

Note: The playbackURL and downloadURL fields should be populated with values obtained as a response from the Upload Audio - Commit API. Furthermore, the provided request body serves as a template, and users are required to replace placeholders such as {{tenantId}}, {{mashupTitle}}, etc. with specific values that align with their individual requirements.


When utilizing the Create Mashup API, it's crucial to include the following compulsory parameters in your payload: 

  • Category Id: A unique identifier for the category to which the mashup is assigned 
  • Category Name: The name of the category associated with the mashup. 
  • Title: A unique and descriptive title for the mashup.
  • Tenant Id: The identifier for the specific tenant or organization to which the mashup belongs. 
  • Content Object: This consists of various content details, such as the file name, content storage, content format, and more.  
  • Mashup Format: Specifies the format or type of the mashup file, such as "Audio" or another relevant format. 
  • Content URL: This includes both the Playback URL, used for streaming or viewing content directly, and the Download URL, enabling users to initiate file downloads from a web server. 

For comprehensive information about the payload requirements and a deeper understanding of the available values within the "mashupParts," you can refer to the comprehensive Mashup API Documentation 

 

3. Response Details 

Upon a successful request the Response status code will be 201 Created, and you will receive a similar response to the following:


Example - Response Body (JSON)

{
    "status": "Published",
    "contentAccessToken": {
        "token": "sv=2021-10-04&se=2023-09-25T07%3A18%3A43Z&sr=c&sp=r&sig=4OTLg4ltwSMNdrCO%2BMTIuMaVqGpyJH4HBxu4H%2F1lpq8%3D",
        "expiresAfter": 15
    },
    "id": "272993",
    "systemId": 0,
    "uuid": "5a82a377-dd98-48a6-a207-cf496c4ebcfb"
}

If the response code is 400, it indicates a bad request. A response code of 401 signifies unauthorized access.  


Read Next

Using REST API - Update Mashup with Custom Attributes