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 Rules

Add the following headers to each API request:

Accept: application/json
Content-Type: application/json
Authorization: Tenant-Auth <MANAGEMENT_KEY>

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.

Authorization

Only authorized users can make requests to the Encoding API. As a part of your Axinom Encoding contract, Axinom provides you configuration data for your Axinom Encoding, specifically:

  • Axinom Encoding URL, e.g. "https://vip-eu-west-1.axinom.com"

  • Tenant Name - human-readable name, e.g. "My Tenant"

  • Management Key - a GUID, 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.

Using Encoding as Axinom Mosaic User

Note
This functionality is available since the release 2.7 (November 2021)

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 which you will be using to talk to Encoding API, and grant this account access to Encoding (it needs only a Video Encoder 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 1h, but you can configure this setting in the Mosaic Admin Portal.

Finally you can add the JWT to your Encoding API requests:

Authorization: Bearer <JWT>
Tip
The exact content of the JWT does not matter, but if you are interested, we recommend using JWT Tool to analyze the token. The token cannot be manipulated, as it is cryptographically signed.

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 a long JSON data structure describing all the options of the requested job. See an example structure below.

{
    "ExternalId": "123456",
    "ExternalType": "movie",
    "ExternalProvider": "ABC",
    "ContentAcquisition" : {
        ...
    },
    "MediaMappings" : {
        ...
    },
    "ContentProcessing" : {
        ...
    },
    "ImageExtraction" : {
        ...
    },
    "Thumbnails" : {
        ...
    },
    "ContentPublishing" : {
        ...
    },
    "MessagePublishers" : [
    	{
        ...
        }
    ]
}
Note
You can find sample Encoding jobs in 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.

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