Encoding API
Axinom Encoding exposes a Web API (hereinafter: Encoding API). The Encoding API can be used to initiate encoding jobs, control the jobs, and access encoding statistics.
General
The Encoding API only accepts connections via HTTPS (not HTTP).
The response format for all API endpoints is JSON - both for success and error responses.
Headers
Add the following headers to each API request:
Accept: application/json
Content-Type: application/json
Authorization: see <<Authentication and Authorization>>
Swagger Endpoint
You can access our Swagger endpoint via https://vip-eu-west-1.axinom.com/api/help.
Quick Start
See Quick Start for a minimalistic request body and for the first steps to run a successful encoding job.
For more details refer to the Job Creation section.
Authentication and Authorization
Only authenticated users can make requests to the Encoding API. There are two possibilities to authenticate yourself as a valid user of the Encoding Service.
Using Mosaic Service Account
This authentication way is available since the release 2.7 (November 2021) and is the preferred one.
Axinom Encoding is a part of Axinom Mosaic Platform.
If you accepted Mosaic Products Evaluation Agreement, you received access to My Mosaic area in the Portal and to the Mosaic Admin Portal.
There you can create a Service Account that you will be using to talk to Encoding API, and grant this account access to Encoding (it needs only a Videos: Encode permission).
To authenticate your service account you can send an API call to Mosaic Identity Service providing its credentials (CLIENT_ID and CLIENT_SECRET). In exchange, you will receive a JWT, granting access to Encoding API. The token is valid by default for 1h, but you can configure this setting in the Mosaic Admin Portal.
Finally, you add the JWT to your Encoding API requests:
Authorization: Bearer <JWT>
The exact content of the JWT does not matter for you, but if you are interested, we recommend using JWT Tool to analyze the token. The token cannot be manipulated, as it is cryptographically signed.
Using Encoding Tenant and Management Key
This authentication way is considered deprecated, but it is supported for backward compatibility for existing customers.
If you create an Axinom Encoding Tenant (don’t confuse it with Mosaic Tenant), you get the following information:
- Axinom Encoding URL, e.g. "https://vip-eu-west-1.axinom.com"
- Tenant Name - human-readable name, e.g. "My Tenant"
- Management Key - a UUID, e.g.
8a276e90-6923-4bda-9f5e-8eddc9159a1e
Management Key shall be passed to each Encoding API request inside an Authorization header:
Authorization: Tenant-Auth <MANAGEMENT_KEY>
It is not possible to recover the Management Key if it’s lost. It is possible to generate a new one by raising a ticket to Axinom Support.
In this authentication scheme there is no additional authorization. Every request with a valid Management Key will be granted access to the Encoding API.
Endpoints
The Encoding API exposes the following endpoints:
| Endpoint | Method | Comment |
|---|---|---|
| /Job | POST | Creates a new encoding job |
| /Job/<job_id>/cancel | POST | Cancels the job |
| /certificate | GET | Returns the Axinom Encoding certificate in base64 form. |
| /reporting/<job_id> | GET | Returns the reporting entry for a specific job |
| /reporting/<year>/<month> | GET | Returns all reporting entries for a specified month |
| /reporting | GET | Returns all reporting entries |
Job Creation
The body of the Job Creation request contains all the options for the requested job. The possible sections of the request are:
{
"ExternalId": "123456",
"ExternalType": "movie",
"ExternalProvider": "ABC",
"ContentAcquisition" : { // Required
...
},
"MediaMappings" : { // Required
...
},
"ContentProcessing" : { // Required
...
},
"ImageExtraction" : {
...
},
"Thumbnails" : {
...
},
"ContentPublishing" : { // Required
...
},
"MessagePublishers" : [
{
...
}
]
}
You can find sample Encoding jobs in the Encoding job samples document.
The sections of the JSON are summarized in the table below.
| Section | Mandatory? | Purpose |
|---|---|---|
| ContentAcquisition | Mandatory | Input Storage (Storage Provider), where to find the input |
| MediaMappings | Mandatory | How to identify the video, audio, and subtitles files in the input storage folder |
| ContentProcessing | Mandatory | Settings related to content processing (e.g. output format, DRM, etc.) |
| ImageExtraction | Optional | Settings for Image Extraction |
| Thumbnails | Optional | Settings for Thumbnails generation |
| ContentPublishing | Mandatory | Output Storage (Storage Provider), where to store the processing results |
| MessagePublishers | Optional | Configured Message Publishers will be used to notify about the job progress |
Detailed descriptions of the individual sections are provided as separate articles.
General Properties in an API Request
The three elements in the top (ExternalId, ExternalType, ExternalProvider), the general properties are just metadata which the client can use to be able to track the job better. Axinom Encoding doesn’t do any processing based on them. These properties reside on the top level of an encoding job definition, outside any section.
{
"ExternalId": "Deadpool 2",
"ExternalType": "Movie",
"ExternalProvider": "Marvel Entertainment"
}
| Property | Value | Description |
|---|---|---|
| ExternalId | String, max length 200 | This field can be used to map the encoding job to some external item (e.g. a database entry or video). Other names often used are contentId and resourceId. |
| ExternalType | String, max length 100 | Type of the item being encoded, e.g. Movie, Trailer or Episode. The values are not limited by the Encoding Service. |
| ExternalProvider | String, max length 100 | Content provider. Can be useful if content from different providers is processed by the same system. The values are not limited by the Encoding Service. |
Job Validation
When a job is submitted, Axinom Encoding performs validation of the request body (JSON). It also extracts, decrypts, and validates the supplied Content Keys for encryption, or, in the DRM Managed Mode, acquires the necessary keys from the Key Service.
If a job was created successfully, Axinom Encoding replies with a HTTP status code 201 and a new Job ID in the body, together with the generated (or extracted) Key ID(s):
{
"JobId": "6a062671-596a-4f09-acfc-0ab800f9e3f1",
"KeyId": "5a601de9-6075-461b-955c-0a155b93b0d3",
"KeyIds": [
"5a601de9-6075-461b-955c-0a155b93b0d3",
"ae355f06-2f01-49d6-a090-6d2ecd486f55",
"be355f06-2f01-49d6-a090-6d2ecd486f55",
"e3d922a0-b059-4131-a936-bee4f435f3a2"
],
"ExternalId": "123456",
"ExternalType": "movie",
"ExternalProvider": "ABC",
}
The KeyId element is returned if there is only one Key.
KeyIds - if there are multiple keys.
KeyId and KeyIds are mutually exclusive.
The three properties with the prefix `"External"`` are simply echoed back to the client.
The Job ID can be used to cancel the job and view its progress.
Job Cancellation
If the job cancellation request was processed correctly, the response echoes the requested URL:
https://.../Job/<job_id>/cancel
As the encoding jobs are long-running tasks, it takes some time to propagate the cancel command and to stop active execution. Once the job is actually cancelled, you will receive an FinalError event with error code 5001.
Certificate
The Axinom Encoding certificate can be used to encrypt credentials sent as a part of the /Job request (see Credentials Protection).
In the release 2.9 and above this endpoint does not require authentication.
Reporting
Using this endpoint, you can get details about a specific job or about all the jobs run in a given month as an array.
See Reporting for further details.
Status Codes
A request result is indicated by an HTTP status code. A 2xx status code (e.g. 200 or 201) indicates success, whereas a 4xx/5xx status code (e.g. 400, 401, or 500) indicates an error.
Failed Authentication
In case a missing or invalid Management Key provided, you get the "User is not authorized to access this resource" response from the API.