Axinom Encoding exposes the Encoding API that can be used to initiate jobs, control these jobs, and also access encoding statistics. Learn the basics of using the Encoding API.

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>>

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

Note
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>
Tip
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

Note
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>
Caution
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" : [
    	{
        ...
        }
    ]
}
Note
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",
}
Important
The KeyId element is returned if there is only one Key. KeyIds - if there are multiple keys. KeyId and KeyIds are mutually exclusive.
Note
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).

Tip
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.

Revision History

The table below lists the document versions and any changes to them.

Version Date Description

1.0

October 7, 2020

Initial version

1.1

October 21, 2020

General properties table added

1.2

March 23, 2021

Removed /version endpoint

2.0

February 25, 2022

Added Mosaic Authentication

3.0

March 08, 2022

'/certificate' does not require authentication anymore

3.1

July 28, 2023

Added a minimal job request example