# Platform 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](https://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

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="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"
                    }
                ]
            }
        ]
    }
}
```

{% endtab %}

{% tab title="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."
}

```

{% endtab %}
{% endtabs %}

## Get Preset Parameters

<mark style="color:blue;">`GET`</mark> `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.&#x20;

#### Path Parameters

| Name   | Type   | Description                     |
| ------ | ------ | ------------------------------- |
| apikey | string | Key generated by platform user. |

{% tabs %}
{% tab title="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;"
                    }
                ]
            }
        ]
    }
}



```

{% endtab %}
{% endtabs %}

## Post Offline file (VOD) - Using parameters&#x20;

<mark style="color:green;">`POST`</mark> `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  | <p>How many B-Frames in the IPB GOP based structure. <br>\[Values 1-10] (Default is 3)</p>                                               |
| 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)                  |

{% tabs %}
{% tab title="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"

            }],

```

{% endtab %}

{% tab title="410 Authorisation failure" %}

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

{% endtab %}

{% tab title="411 Database Error" %}

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

{% endtab %}

{% tab title="412 Parsing Error" %}

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

{% endtab %}

{% tab title="413 Missing fields or value in a field " %}

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

{% endtab %}

{% tab title="414 Invalid entry" %}

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

{% endtab %}

{% tab title="415 Error in value of encoding type" %}

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

{% endtab %}

{% tab title="417 Invalid input" %}

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

{% endtab %}
{% endtabs %}

## Post Offline file (VOD) - Using Preset ID

<mark style="color:green;">`POST`</mark> `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 |             |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Example Post Command

An example of creating a ladder of two encodes from the same source file.&#x20;

```
{
    "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.&#x20;