Encode a Video using API
This article is a part of the Encoding Quick Start Guide.
Overview
- Create storage — set up input and output blob containers
- Upload a video — upload a source video to the input container
- Create a job request — build the JSON payload for the encoding job
- Authenticate — obtain a JWT for the API call
- Submit the job — submit the job request to the Encoding Service
- Wait for completion — monitor for a success or failure notification from Encoding Service
- Preview the result — verify the output plays back correctly
1. Create Storage
Follow these steps to enable Mosaic Storage and collect the credentials you will need for step 3.
a. Enable Cloud Storage
- Go to the Admin Portal.
- Select the environment you are working in.
- In the services list, click Hosting Service.
- In the action panel, click Cloud Storage.
- If storage is not yet enabled, click Enable Storage in the action panel. This can take a few minutes.
b. Copy your credentials
Once storage is enabled, the Cloud Storage Details panel shows three values. You will need the first two:
| Field | What to copy |
|---|---|
| Storage Account Name | Copy this — you'll use it as-is in CredentialsName |
| Storage Account Key | Copy this — you'll encrypt it for CredentialsSecret |
| Connection String | Not needed for this guide |
c. Encrypt the Storage Account Key
Open the Credentials Protection Tool, paste the Storage Account Key into the tool, and copy the encrypted output. You will use this in step 3.
d. Build your storage URLs
Your input and output UriPath values follow this pattern:
https://<Storage Account Name>.blob.core.windows.net/<container>/<folder>/
The default containers created by Mosaic Hosting Service are:
| Container | Purpose |
|---|---|
video-input | Where you upload the source video |
video-output | Where encoded files are written |
For example, if your Storage Account Name is mystorage and you want a subfolder called my-movie:
- Input:
https://mystorage.blob.core.windows.net/video-input/my-movie/ - Output:
https://mystorage.blob.core.windows.net/video-output/my-movie/
If you want to try playing back the result, enable Public Read Access on the video-output container in the Mosaic Hosting Service.
2. Upload a video
Upload a short .mp4 to a subfolder in your input container using My Mosaic → Encoding.
3. Create a job request
We create a CMAF stream that gives us a good coverage of the platforms your users are likely using.
For easy detection of the source media in the acquisition folder, we set MediaDetection to Convention to use our file naming convention.
{
"ContentAcquisition": {
"Provider": "AzureBlob",
"UriPath": "https://<Storage Account Name>.blob.core.windows.net/video-input/",
"CredentialsName": "<Storage Account Name>",
"CredentialsSecret": "<encrypted Storage Account Key>",
"CredentialsProtection": "Encrypted"
},
"MediaMappings": {
"MediaDetection": "Convention"
},
"ContentProcessing": {
"OutputFormat": ["Cmaf"]
},
"ContentPublishing": {
"Provider": "AzureBlob",
"UriPath": "https://<Storage Account Name>.blob.core.windows.net/video-output/",
"CredentialsName": "<Storage Account Name>",
"CredentialsSecret": "<encrypted Storage Account Key>",
"CredentialsProtection": "Encrypted"
},
"MessagePublishers": [
{
"Type": "azureservicebusqueue",
"Connection": "<encrypted Service Bus connection string>",
"CredentialsProtection": "Encrypted"
}
]
}
MessagePublishers is optional — you can omit it and the job will still run. However, configuring a message queue is the easiest way to know when encoding has finished, as the Encoding Service will publish a JobSuccess or FinalError notification to it automatically.
Replace each placeholder using the values from step 1:
| Placeholder | Where to get it |
|---|---|
<Storage Account Name> | Copy as-is from Cloud Storage Details in Admin Portal |
<encrypted Storage Account Key> | Paste the Storage Account Key into the Credentials Protection Tool and copy the output |
<encrypted Service Bus connection string> | Encrypt your Azure Service Bus connection string the same way using the Credentials Protection Tool |
If your files are inside a subfolder within the container, append it to the UriPath (e.g. .../video-input/my-movie/). If you uploaded directly to the container root, no subfolder is needed.
4. Authenticate
a. Create a Service Account
- Go to the Admin Portal and select your environment.
- Click Service Accounts → New.
- Give it a name and confirm. The portal displays the Client ID and Client Secret once — copy both and store them somewhere safe. The secret cannot be retrieved again.
- Click Permissions and grant the Videos: Encode permission.
b. Get a JWT
On the Service Account details page, click Generate Access Token. Copy the token — this is the Bearer JWT you will use in step 5.
The token is valid for 1 hour by default. If it expires before you submit the job, generate a new one the same way.
5. Submit the job
POST https://vip-eu-west-1.axinom.com/job
Authorization: Bearer <JWT>
Content-Type: application/json
A 201 response confirms the job is queued. Encoding is done when you receive a JobSuccess or FinalError message via your message publisher.
If you are using the US region endpoint, the URL is https://vip-us-west-2.axinom.com/job
6. Wait for completion
Once the job is queued, the Encoding Service processes the video asynchronously and publishes a JSON message to your configured message broker when done. Listen for a JobSuccess message for a successful result, or FinalError for a failure.
Supported message brokers include Azure Service Bus and RabbitMQ — the broker is configured via the MessagePublishers field in your job request (see step 3).
7. Preview the result
Open the HLS manifest (manifest.m3u8) from your output folder directly in Chrome or Safari.
You also have the DASH manifest (manifest.mpd) at your disposal. The great thing about CMAF stream format is that you get both the DASH and HLS manifest, so it gives you a very good platform coverage right out of the box.
If you're using Chrome or Safari, and if you did not protect the stream using DRM, you can just load the manifest.m3u8 URL in it and the stream should start playing right in the browser.
If you're using an another browser, or you protected your stream with DRM (which we encourage you to do eventually), you might need to use a separate video player, such as Shaka Player.