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

Login into the platform, then go to System on the left-hand navigation panel and select Users.
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.
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.

{
    "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"
                    }
                ]
            }
        ]
    }
}

{
    "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.

{
    "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)

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

            }],

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

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

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

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

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

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

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

***************************************************************************
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 support@v-nova.com and include the API response concerned.

PreviousPerform the Encode and View Content NextDecoding

Last updated 1 year ago