Platform API

This page provides a reference to the V-Nova Platform for encoding LCEVC-enhanced x264 and x265 encodes using the REST API .

Before you start

The Platform’s REST API is designed to rapidly create automated encoding solutions and to facilitate the integration of LCEVC-enhanced encoding into other services and platforms. To learn more about the options for integrating LCEVC contact V-Nova at www.v-nova.com/contact.

This section details how to use the platform’s API to retrieve encode information from a previous job or start a new job with defined parameters for VOD or live content.

In order to authenticate your user account with the platform's API you must acquire an API key. Please bear in mind this key will give full access to your account and it is therefore recommended to store the key in a secure location to guard against the potential security risk of exposing an account API key to third parties. The platform API only supports JSON.

To access your API key

1. Login into the platform, then go to System on the left-hand navigation panel and select Users.

2. Edit the user you wish to assign API access to. At the bottom of the user page you will find the API Key for that user.

3. If the API key has not been generated, then go to API Key Refresh, select Generate and save the user. You may need to logout and back in again to retrieve the key.

Get VOD asset details

GET https://api.v-nova.com/production/prod_vod/v-nova/{username}/{contentid}

This will allow you to get the details of your account's encodes, if you specify a content ID it will only pull back the information of that particular job, if not it will pull back information on all of the encodes. Usign content ID is a GET method only.

Headers

Name	Type	Description
apikey	string	Key generated by platform for user.

200 VOD Listing successful

{
    "Message": "VOD Listing Successful ",
    "Username": "Demo",
    "Total VOD Contents": 1,
    "EncodingParameters": {
        "packaging": {
            "Description": "Packaging Options available on the platform",
            "Values": {
                "Hls_ts": "0",
                "Dash_fmp4": "1"
            }
        },
        "encodingType": {
            "Description": "Encoding Engine to be used for the encoding of this profile",
            "Values": [
                "2",
                "3"
            ]
        },
        "width": {
            "Description": "width of the encoded video for this profile"
        },
        "height": {
            "Description": "height of the encoded video for this profile"
        },
        "transform": {
            "Description": "specify the transform type for encoding.",
            "Values": [
                "dd",
                "dds"
            ]
        },
        "ditherStrength": {
            "Description": "setting strength of dither"
        },
        "x264Preset": {
            "Description": "setting preset parameters for x264",
            "Values": [
                "very fast",
                "fast",
                "medium",
                "slow",
                "very slow",
                "placebo",
                "dual pass"
            ]
        },
        "QpMin": {
            "Description": "Advanced perseus parameter forspecifying the minimum quanatization for the encoding in thisprofile."
        },
        "QpMax": {
            "Description": "Advanced perseus parameter forspecifying the maximum quanatization for the encoding in thisprofile."
        },
        "maxgop": {
            "Description": "maximum no of gop present in a chunk"
        },
        "videoBitrate": {
            "Description": "video bitrate per second for the video profile"
        },
        "audioBitrate": {
            "Description": "audio bitrate per second for the video profile"
        }
    },
    "VodAssets": {
        "catalogue:": [
            {
                "Title": "XXX",
                "ContentId": "XXXXXX",
                "ContentDuration": "00:00:10.00",
                "IsPremium": false,
                "IsEnabled": true,
                "AdURL": "https://s3.eu-west-2.amazonaws.com/XXXX",
                "Packaging": "HLS - ts chunks",
                "ManifestURL": "https://s3.eu-west-2.amazonaws.com/origin-lon.v-nova.com/XXXX",
                "ThumbnailImage": "https://s3.eu-west-2.amazonaws.com/origin-lon.v-nova.com/images/XXXX",
                "PosterImage": "https://s3.eu-west-2.amazonaws.com/origin-lon.v-nova.com/images/XXXX",
                "Description": "",
                "Cast": "",
                "NoofProfiles": "1",
                "Chunksize": "10",
                "Profiles": [
                    {
                        "Resolution": "1920X1080",
                        "Bitrate": "1024000",
                        "Maxgop": "50",
                        "ProfileNo": 1,
                        "Size": "1.250000",
                        "Audiobitrate": "64"
                    }
                ]
            }
        ]
    }
}

411 Database error, incorrect contnet ID

{
    "Error Code": "411 ",
    "Message": "Database Error ",
    "Username": "Demo ",
    "Query Error": "sql: no rows in result set ",
    "Error": "There was an issue fetching the data from the database. 'XXXXX' does not exist."
}

Get Preset Parameters

GET https://api.v-nova.com/production/prod_vod/presets/{presetID}

/presets returns a list of presets and their parameters. /presets/{presetID} retrieves the preset's parameters that can be used to populate all parameters in a post job.

Path Parameters

Name	Type	Description
apikey	string	Key generated by platform user.

200

{
    "Message": "VOD Presets Listing Successful ",
    "Total Presets ": 1,
    "VodPresets": {
        "catalogue:": [
            {
                "PresetID": "200",
                "Title": "720p_50/60_Single_HQ",
                "NoofProfiles": "1",
                "Profiles": [
                    {
                        "EncodingType": "2",
                        "ApplyRateControl": "0",
                        "Width": "1280",
                        "Height": "720",
                        "VideoBitrate": "1740",
                        "AudioBitrate": "96",
                        "ApplyLcevc": "on",
                        "X264Preset": "medium",
                        "X264RateControl": "cbr",
                        "X265Preset": "",
                        "X265RateControl": "",
                        "LcevcTune": "vq",
                        "ScalingMode": "auto",
                        "Transform": "auto",
                        "Bframes": "3",
                        "Maxgop": "50",
                        "MAdaptiveDownsampling": "auto",
                        "HFstrength": "NA",
                        "LFstrength": "NA",
                        "DitherCheck": "auto",
                        "Strength": "NA",
                        "QpMin": "NA",
                        "QpMax": "NA",
                        "AdditionalParameters": "-pix_fmt yuv420p ",
                        "AdditionalEILParameters": "accel_num_worker_threads=8;rc_pcrf_base_rc_mode=cbr;lcevc_tune=vq;preset=medium;"
                    }
                ]
            }
        ]
    }
}

Post Offline file (VOD) - Using parameters

POST https://api.v-nova.com/production/prod_vod/v-nova/{username}

The body of a post must take the form below. If a presetID is set the profile parameters do not need to be defined. See next chapter. We have set default values in the below body. If you wish to generate more than one profile, simply duplicate the profile parameters in the same POST string.

Headers

Name	Type	Description
apikey	string	Key generated by platform

Request Body

Name	Type	Description
title	string	Title for encode job
url	string	URL of source.
cast	string	Text description.
description	string	Text description.
Rating	string	Audience rating, text field.
segmentDurationSecs	number	GOP Segment duration. (Default is '10')
encodingMode	boolean	Define which codec to use. [Values '0' MPEG-5 LCEVC x.264, '1' MPEG-5 LCEVC x.265] (Default '0')
packagingMode	boolean	[Values '0' HLS with transport stream base, '1' DASH with fragmented mp4]. (Default '1')
presetID	number	Numerical ID of the preset as defined per user.
encodingType	boolean	AWS encoding engine to be used. ['2' ECS Fargate, '3' EC2] (Default EC2)
applyRateControl	boolean	[Values 0/1]
width	number	Pixel count of the width of the output video. (Default is 1920)
height	number	Pixel count of the height of the output video. (Default is 1080)
videoBitrate	number	Video bitrate defind in Kbps. (Default is 1000)
audioBitrate	number	Audio bitrate defined in Kbps. (Default 64Kbps)
applyLcevc	boolean	To set a LCEVC or native encode. [Values on/off] (Default on)
x26*Preset	boolean	Preset parameters for x264 or x265 as defined. [Values ery Slow, Slow, Very fast, Fast, Medium, Placebo, Dual-Pass] (Default is Medium)
x26*RateControl	boolean	Rate control for either x264 or x265 as defined. [Values cbr & crf] (Default is crf)
lcevcTune	boolean	Values vq, vmaf, ssim, psnr. (Default is ‘vq’)
transform	boolean	Specify the transform type for encoding. Values [dd and dds]. Default value is dds.
Scaling mode	boolean	auto, 1D 2D (Default 2D)
Bframes	number	How many B-Frames in the IPB GOP based structure. [Values 1-10] (Default is 3)
maxgop	number	Maximum value GOP present in a chunk. (Default is 50)
ditherCheck	boolean	(Value on or off)
Strength	number	Wetting strength of dither. [Value 1-10] (Default is 5)
QpMin	number	Advanced parameter for specifying the maximum quantization for the encoding in this profile. [Value 1-51] (Default 25)
QpMax	number	Advanced parameter for specifying the maximum quantization for the encoding in this profile. [Value 1-51] (Default 30)

200

***************************************************************************
Response:-
***************************************************************************
{
        "title" : " API Document test  ",
        "url" : "http*****.mp4",
        "cast" : "",
        "description" : "",
        "rating" : "",
        "packaging" : "1",
        "segmentDurationSecs" : "10",
        "encodingMode" : "0",
        "packagingMode" : "0",
        "presetID" : "",
        "profiles" : [
            {
                "encodingType" : "2",
                "applyRateControl" : "0",
                "width" : "1920",
                "height" : "1080",
                "videoBitrate": "1000",
                "audioBitrate" : "64",
                "applyLcevc" : "on",
                "x264Preset" : "veryslow",
                "x264RateControl" : "crf",
                "x265Preset" : "",
                "x265RateControl" : "",
                "lcevcTune"   : "vq",
                "transform" : "auto",
                "scalingMode" : "auto",
                "bframes"     : "3" ,
                "maxgop" : "50",
                "mfilters" : "auto",
                "filter1strength" : "",
                "filter2strength" : "",
                "MAdaptiveDownsampling" : "",
                  "HFstrength" : "",
                  "LFstrength" : "",
                "ditherCheck" : "auto",
                "strength" : "5",
                "QpMin" : "25",
                "QpMax" : "30"

            }],

410 Authorisation failure

{
    "Error Code": "410 ",
    "Message": "Authorisation failure ",
    "Username": "Demo ",
    "Error": "Error description"
}

411 Database Error

{
    "Error Code": "411 ",
    "Message": "Database Error ",
    "Username": "Demo ",
    "Error": "Error description"
}

412 Parsing Error

{
    "Error Code": "412",
    "Message": "Parsing Error ",
    "Username": "Demo ",
    "Error": "Error description"
}

413 Missing fields or value in a field

{
    "Error Code": "413",
    "Message": "Message ",
    "Username": "Demo ",
    "Error": "Error description"
}

414 Invalid entry

{
    "Error Code": "414",
    "Message": "Invalid Entry ",
    "Username": "Demo ",
    "Error": "Error description"
}

415 Error in value of encoding type

{
    "Error Code": "415",
    "Message": "Message ",
    "Username": "Demo ",
    "Error": "Error description"
}

417 Invalid input

{
    "Error Code": "417",
    "Message": "Message ",
    "Username": "Demo ",
    "Error": "Error description"
}

Post Offline file (VOD) - Using Preset ID

POST https://api.v-nova.com/production/prod_vod/v-nova/{username}

Post offline file (VOD) with Preset's.

Path Parameters

Name	Type	Description
apikey	string

200

***************************************************************************
Response:-
***************************************************************************
{
        "title" : " API Document test  ",
        "url" : "http*****.mp4",
        "cast" : "",
        "description" : "",
        "rating" : "",
        "packaging" : "1",
        "contentCategoryID" : "77",
        "segmentDurationSecs" : "10",
        "encodingMode" : "0",
        "packagingMode" : "0",
        "presetID" : "",

Example Post Command

An example of creating a ladder of two encodes from the same source file.

{
    "title" : "ABC1",
    "url" : "input.mp4",   
    "cast" : "AC",
    "description" : "DE",
    "rating" : "AA",
    "packaging" : "1"
    "segmentDurationSecs" : "10",
    "encodingMode" : "0",
    "packagingMode" : "0",
    "presetID" : "",
    "profiles" : [
        {
            "encodingType" : "2",
            "applyRateControl" : "0",
            "width" : "1920",
            "height" : "1080",
            "videoBitrate": "1000",
            "audioBitrate" : "64",
            "applyLcevc" : "on",
            "x264Preset" : "veryslow",
            "x264RateControl" : "crf",
            "x265Preset" : "",
            "x265RateControl" : "",
            "lcevcTune"   : "vq",
            "transform" : "auto",
            "scalingMode" : "auto",
            "bframes"     : "3" ,
            "maxgop" : "50",
            "MAdaptiveDownsampling" : "auto",
            "HFstrength" : "",
            "LFstrength" : "",
            "ditherCheck" : "auto",
            "strength" : "",
            "QpMin" : "",
            "QpMax" : ""
        },
        {
            "encodingType" : "2",
            "applyRateControl" : "0",
            "width" : "1920",
            "height" : "1080",
            "videoBitrate": "1000",
            "audioBitrate" : "64",
            "applyLcevc" : "on",
            "x264Preset" : "veryslow",
            "x264RateControl" : "crf",
            "x265Preset" : "",
            "x265RateControl" : "",
            "lcevcTune"   : "vq",
            "transform" : "auto",
            "scalingMode" : "auto",
            "bframes"     : "3" ,
            "maxgop" : "50",
            "MAdaptiveDownsampling" : "auto",
            "HFstrength" : "",
            "LFstrength" : "",
            "ditherCheck" : "auto",
            "strength" : "",
            "QpMin" : "",
            "QpMax" : ""
        }
        ],

Support

Errors are returned within standard http syntax, these are shown above in the response tab of the GET or POST headers. If you experience any errors or wish to file a bug report, please contact your V-Nova representative or [e-mail] and include the API response concerned.