LightFlow API documentation (1.0.0)

Download OpenAPI specification:Download

Introduction

LightFlow is a video platform that leverages the use of perceptual video quality metrics and machine learning algorithms to optimize the quality of your videos at the most effective bitrate. Getting started to use LightFlow is quite easy, it is API driven and can be easily integrated in your current media workflow.

Get an API token

LightFlow API uses a token for authentication. A default token is generated for every new user. You can view it in the Settings view of LightFlow portal.

Token generation view

Publish your first asset

LightFlow optimizes quality, delivers streams and applies advanced cognitive features on videos. You can initiate any of these services by publishing (posting) a new asset:

curl -XPOST 'https://api.lightflow.media/assets' \
  -H 'authorization: Bearer API_KEY' \
  -H 'content-type: application/json' \
  -d '{
      "parameters": {
        "input": {
          "urlPath": "https://xx.com/your-video.mp4"
        },
        "perceptual-quality": {
          "h264": {
            "maxBitrate": 8000,
            "minBitrate": 250,
            "maxResolution": 1080,
            "targetQuality": 100
          }
        }
      }
    }'

Quite intuitive! We right created an optimized version of your-video.mp4 asset and packaged it to be delivered as MP4 files, HLS and MPEG-DASH streams.

Watch the result!

Your asset is ready to be watched! You can watch your video, together with an analysis of the output quality, by clicking on the view icon of the Monitoring view of [LightFlow portal](https://dashboard.lightflow.media).


You can also create a playback URL using the asset uuid and watch the video in your preferred browser, delivered using HLS or MPEG-DASH protocols.

HLS stream URL:

https://video.lightflow.media/hls/[UUID]/master.m3u8

MPEG-DASH stream URL:

https://video.lightflow.media/dash/[UUID]/manifest.mpd

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response is a JSON with the following format:

{
  "message": "asset not found"
}

Supported formats

LightFlow supports a wide range of media containers, video and audio codecs:

Containers 3g2, 3gp, aac (dts), asf, avi, dif,
dv, f4v, flv, m4a, m4v, mkv, mj2, mov,
mp3, mp4, mpeg, mpegts, mpg, mxf,
ogg, ps, ts, webm, wmv
Video codecs DiVX, DV, DV25, DV50, DVCPro 50,
H.263, H.264, H.265 (HEVC),
IMX 30, ProRes, Motion-JPEG,
MPEG HDV 1080i, MPEG V1 Layer 2,
MPEG2 V2 (m2v1), MPEG4 Part 2,
MPEG XDCAM HD422, VP8, VP9, WMV
Audio codecs AAC, HE-AAC, mp3 (MPEG V1 Layer 2 & 3),
PCM, WMA2, WMV (pro)

Authentication

bearerAuth

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Publish an asset

You can publish your videos in LightFlow sending a POST request to the /assets endpoint, indicating in the urlPath property the Url of the video file you would like to publish.

curl -XPOST 'https://api.lightflow.media/assets' \
  -H 'authorization: Bearer API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ \
    "parameters": { \
      "input": { \
        "urlPath": "http://someserver.com/VideoSample.mp4" \
      }, \
      "perceptual-quality": { \
        "h264": { \
          "maxBitrate": 8000, \
          "minBitrate": 250, \
          "maxResolution": 1080, \
          "targetQuality": 100 \
        } \
      } \
    } \
  }'

The response will include the unique identifier of the published asset and its playback Urls. Playback Urls are the Urls that can be used in any HLS/MPEG-DASH compatible player to watch the content.

Apart from supporting inputs based on an HTTP Url, LightFlow can retrieve your content directly from your storage provider. Most of known storage providers are currently supported by LightFlow:

  • Akamai Netstorage
  • Google Cloud Storage
  • Amazon S3
  • Azure Blob Storage
  • FTP/SFTP
  • Scality
  • Object Matrix
  • etc

You can take a look to LightFlow API Reference guide to get further information about how to setup your own storage in LightFlow.

Playback URLs

When LightFlow Delivery is selected as the delivery mechanism, assets are ready to be watched as soon as publish process is done. In [LightFlow portal](https://dashboard.lightflow.media) video asset can be watched, together with an analysis of its quality, by clicking on the view icon of the Monitoring view.


Playback Url's can also be composed following below Url format, which will allow you to play your assets in any HLS/MPEG-DASH compatible player.

HLS stream URL:

https://video.lightflow.media/hls/[UUID]/master.m3u8

MPEG-DASH stream URL:

https://video.lightflow.media/dash/[UUID]/manifest.mpd

Video settings

As part of the publish process, LightFlow analyzes the complexity and characteristics of your video asset and decides smartly which is the combination of encoding parameters that most improve its watching experience. This is what LightFlow calls smart encoding process. To make easier the adaptation of this smart algorithm to different customer needs, LightFlow smart encoding engine offers a wide set of setting parameters. Right below you can find the commonly used ones. More detailed information about setting parameters can be found in the API reference guide.

  • targetQuality: Target video quality for the optimal bitrate ladder calculation expressed as an LQI value (0-100, being 100 the highest quality). LQI is a predictive measure of quality that is based in artificial intelligence.
  • maxBitrate: Upper bitrate limit for the optimal bitrate ladder calculation. LightFlow will consider renditions at higher bitrates until any of the following conditions are met:
    • Max Bitrate is reached.
    • targetLQI is reached.
    • Next bitrate does not bring significant perceptual quality increase.
  • minBitrate: Minimum bitrate eligible for the lowest quality rendition.
  • maxMinBitrate: Maximum bitrate eligible for the lowest quality rendition. The bitrate of the lowest quality rendition can be forced setting minBitrate = maxMinBitrate.
  • maxResolution: 720p or 1080p for SD/HD; 1440p or 2160p for 4K.
  • maxFPS: Maximum frames per second to be used for the asset (ex: "25"). Set to "auto" to passthrough frames per second of the video source.
  • maxRenditions: Maximum number of renditions to generate. Its default value is 0, what means LightFlow will select the max number of renditions intelligently.

LightFlow Smart Encoding is available for H.264, VP9 and H.265, both for SD/HD and 4K type of outputs.

Publishing an asset using LightFlow UI

To publish a video, go to the Publish section of the LightFlow portal, and follow 5 simple steps:

1. Select Input

Once the input (S3, NetStorage, FTP, other...) is selected, the following information is required:

  • http/s URL: URL to the video (Youtube and Vimeo URLs are supported), or alternatively
  • path: path of the input video

alternate Input

The supported input formats can be checked here (https://lightflow.media/documentation.html#section/Supported-formats).

2. Select your business priority

Ouputs generated by Lightflow can be customized to take into account your business priorities. Do you concern about video quality or costs savings? Five profiles can be applied, from left (will maximixe costs savings over quality) to right (will maximize quality over costs savings).

alternate Optimization

3. Select which Optimization you want to apply

Three optimization features can be applied: Optimization for SD/HD, Optimization for 4K or Both.

  • Optimization for SD/HD: LightFlow will calculate the optimal bitrate ladder for up to 1080p with H.264 codec.
  • Optimization for 4K: LightFlow will calculate the optimal bitrate ladder for up to 4k with H.265 codec.
  • Both: Both optimizations will be performed.

alternate Optimization

Input filters & packaging options

These are options that apply to any selected configuration:

  • Input Filters: to deinterlace the input video, check the Deinterlace input video box.
  • Output Packaging:
    • Enable MP4 files: Default option.
      • Enable DASH packaging: The transcoded .mp4 content will be packaged into DASH format. This option is ENABLED by default if LightFlow is selected as delivery platform.
      • Enable HLS packaging: The transcoded .mp4 content will be packaged into HLS format. This option is ENABLED by default if LightFlow is selected as delivery platform.

4. Select Encoder

Three options available:

  • LightFlow UltraFast encoder: default option.
  • Your own encoder: Currently AWS MediaConvert and Brightcove encoders are supported.
  • No encoder: The output will be the list of optimal bitrates/resolutions.

alternate Delivery

5. Select Output/delivery

Select the location in which your optimized videos should be stored:

  • LightFlow: LightFlow platform will store and deliver the video.
  • Other Output location: In this case, the following information is required:
    • Path: path of the output directory where the resulting .mp4 files (and HLS/DASH files if selected) for each bitrate/resoluiton will be stored. For example, if the input file name is VideoSample.mp4, and the output path is /OutputDirectory/VideoSampleOutput/, then the resulting output .mp4 files will be uploaded in the output path as follows:
      • /OutputDirectory/VideoSampleOutuput/ output_300.mp4
        • /OutputDirectory/VideoSampleOutuput/ output_720.mp4
        • /OutputDirectory/VideoSampleOutuput/ output_1080.mp4

alternate Encoder

5. Review and publish your asset

Click "Publish Asset!" and you are done!

alternate Review

Set up an S3 storage

To define an S3 bucket as input/output for the videos, go to the Input & Output section of the LightFlow portal, and click on the Amazon S3 icon. To create a new S3 storage location, the following information is required:

Create a Storage location

  • Name: Name of the S3 Location as it will be displayed in LightFlow.
  • Bucket: AWS bucket name.
  • Access key: S3 account access key.
  • Secret key: S3 account secret key.
  • Type: Select either input, output or both input+output (the same bucket can be selected as input and also as repository for the output files).

alternate Input-Output

Create an S3 Storage with the API

curl -XPOST 'https://api.lightflow.media/inputs-outputs' \
  -H 'authorization: Bearer API_KEY' \
  -H 'content-type: application/json' \
  -d '{
      "storageId": "s3",
      "storageType": "input-output",
      "name": "S3 bucket",
      "args": [{
        "id": "bucket",
        "value": "custom_bucket"
      },{
        "id": "accessKey",
        "value": "access_key"
      },{
        "id": "secretKey",
        "value": "secret_key"
      }]
    }'

The response will include the unique identifier of the input/output storage location, which can be later selected as input InputId and/or output OutputId when posting a video.

Set up Akamai Netstorage

To define Akamai NetStorage as input/output for the videos, go to the Input & Output section of the LightFlow portal, and click on the Akamai NetStorage icon. To create a new Netstorage location, the following information is required:

Create Storage endpoint

  • Name: Name of the NetStorage Location as it will be displayed in LightFlow.
  • Hostname: NetStorage hostname, as provided by Akamai.
  • Username: username for an FTP Upload account in Akamai NetStorage(1).
  • Password: password for the FTP Upload account in Akamai NetStorage.
  • Type: Select either input, output or both input+output (the same bucket can be selected as input and also as repository for the output files).

alternate Input-Output

(1) An FTP Upload Account in NetStorage is required.

Create an Akamai NetStorage with the API

curl -XPOST 'https://api.lightflow.media/inputs-outputs' \
  -H 'authorization: Bearer API_KEY' \
  -H 'content-type: application/json' \
  -d '{
      "storageId": "netstorage",
      "name": "My own NetStorage account",
      "storageType": "input-output",
      "args": [{
            "id": "host",
            "value": "netstorage.hostname"
        }, {
            "id": "username",
            "value": "username"
        }, {
            "id": "password",
            "value": "password"
        }]
    }'

The response will include the unique identifier of the input/output storage location, which can be later selected as input InputId and/or output OutputId when publishing a video asset.

Set up a GCS storage

To define a Google Cloud Storage bucket as input/output for the videos, go to the Input & Output section of the LightFlow portal, and click on the Google Cloud Storage icon. To create a new Google Storage location, the following information is required:

Create Storage endpoint

  • Name: Name of the Google Cloud Storage Location as it will be displayed in LightFlow.
  • Bucket: Google Cloud Storage bucket name.
  • Access key: Google Cloud Storage account access key.
  • Secret key: Google Cloud Storage account secret key.
  • Type: Select either input, output or both input+output (the same location can be selected as input and also as repository for the output files).

alternate Input-Output

Create a Google Cloud Storage location with the API

curl -XPOST 'https://api.lightflow.media/inputs-outputs' \
  -H 'authorization: Bearer API_KEY' \
  -H 'content-type: application/json' \
  -d '{
      "storageId": "gcs",
      "storageType": "input-output",
      "name": "My Google Storage bucket",
      "args": [{
        "id": "bucket",
        "value": "custom_bucket"
      },{
        "id": "accessKey",
        "value": "access_key"
      },{
        "id": "secretKey",
        "value": "secret_key"
      }]
  }'

The response will include the unique identifier of the input/output storage location, which can be later selected as input InputId and/or output OutputId when publishing a video asset.

Set up a FTP or SFTP storage

To define a FTP/SFTP repository as input/output for the videos, go to the Input & Output section of the LightFlow portal, and click on the FTP/SFTP icon. To create a new FTP/SFTP location, the following information is required:

Create Storage endpoint

  • name: Name of the FTP/SFTP Location as it will be displayed in LightFlow.
  • hostname: FTP/SFTP server hostname.
  • port: FTP/SFTP server port.
  • username: user name in the FTP/SFTP server.
  • password: password of the FTP/SFTP user.
  • Is secure server: Checked for SFTP.
  • type: select input, output or input/output.

Create an FTP/SFTP location with the API

curl 'https://api.lightflow.media/inputs-outputs'
-H 'authorization: Bearer
-H 'content-type: application/json'
--data-binary '{
    "storageId":"ftp",
    "storageType":"input-output",
    "name":"My own FTP storage"
    "args":[{
        "id":"host",
        "value":"ftp.lightflow.com"
    },{
        "id":"port",
        "value":21"
    },{
        "id":"username",
        "value"user"
    },{
        "id":"password",
        "value"pwd"
    },{
        "id":"secure",
        "value"false"

    }]
  }'

The response will include the unique identifier of the input/output storage location, which can be later selected as input InputId and/or output OutputId when publishing a video asset.

Watermarks

LightFlow supports adding one or more watermarks to your assets. A watermark is an image overlaid on a video which is often used for security and/or branding reasons.

You can add watermarks to your video using the watermarks filter of the [Asset Creation API](https://dashboard.lightflow.media/documentation.html#tag/Assets/paths/~1assets/post). You will need to indicate from where the overlay image should be retrieved (HTTP url or using any of the storage providers supported by LightFlow) and the watermark placement options.

curl -XPOST 'https://api.lightflow.media/assets' \
  -H 'authorization: Bearer API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ \
      "parameters": { \
          "input": { \
              "urlPath": "http://someserver.com/VideoSample.mp4" \
            }, \
            "output": { \
              "filters": { \
                  "watermarks": [{ \
                      "input": { \
                          "urlPath": "https://dashboard.lightflow.media/assets/img/lightflow-135x42-bw.png" \
                      }, \
                      "config": { \
                          "opacity": 100, \
                          "top": "100", \
                          "left": "100" \
                      } \
                    }] \
                } \
            }, \
            "perceptual-quality": { \
              "h264": { \
                  "maxBitrate": 8000, \
                    "minBitrate": 250, \
                    "maxResolution": 1080, \
                    "targetQuality": 100 \
                } \
            } \
      } \
    }'

Placement settings

  • opacity: How opaque the overlay should appear (0-100).
  • top: Top position of the watermark as a percent ("5%") of the video height or as an absolute pixel value ("100").
  • bottom: Bottom position of the watermark as a percent ("5%") of the video height or as an absolute pixel value ("100").
  • left: Left position of the watermark as a percent ("5%") of the video width or as an absolute pixel value ("100").
  • right: Right position of the watermark as a percent ("5%") of the video width or as an absolute pixel value ("100").
  • width: Width of the watermark as a percent ("20%") of the video width or as an absolute pixel value ("120"). If both, width and height are empty, source image width and height will be used. If only height is specified, width is automatically calculated to keep aspect ratio.
  • height: Height of the watermark as a percent ("20%") of the video width or as an absolute pixel value ("150"). If both, width and height are empty, source image width and height will be used. If only width is specified, height is automatically calculated to keep aspect ratio.

Using Callbacks

whenever you publish an asset in Lightflow you can define callbacks which will be triggered when it has been processed. This will allow you to track your assets status asynchronously. Whenever an asset processing is finished, successfully or not, LightFlow will make a request to the addresses defined in your callbacks configuration, so you can do your own actions on your end.

Callbacks are defined in the endpoint responsible of publishing new assets

curl -XPOST 'https://api.lightflow.media/assets' \
  -H 'authorization: Bearer API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ \
      "parameters": { \
          "input": { \
              "urlPath": "http://someserver.com/VideoSample.mp4" \
          }, \
          "perceptual-quality": { \
              "h264": { \
                  "maxBitrate": 8000, \
                  "minBitrate": 250, \
                  "maxResolution": 1080, \
                  "targetQuality": 100 \
              } \
          }, \
          "callbacks": [ \
              { \
                  "url":"https://callback.epiclabs/ingest", \
                  "headers":[ \
                    { \
                      "name": "Authorization", \
                      "value" : "Bearer <JWT TOKEN>" \
                    }, \
                    { \
                        "name": "X-Custom-Header", \
                        "value" : "X-Custom-Header-Value"
                    } \
                  ], \
                  "method":"POST", \
              } \
          ] \'
      } \
    }'

Arguments

  • url: Defines the public accesible endpoint exposed by you and that will be called by LightFlow when the callback mechanism is triggered. Mail adressess are also supported following the format "mailto:johndoe@epiclabs.io". A mail will be delivered to the specified address.

  • headers: Optional field, its default value is empty. Accepts an array of objects with the keys 'name' and 'value'. List of HTTP headers that will be sent by LightFlow when doing a request to your endpoint.

  • method: Optional field, its default value is 'POST'. HTTP request methods. Possible values

    • GET: As it is a GET request, request body will be empty. Parameters 'status' and 'endDate' are variables provided by LighFlow to your endpoint as query params.

    • POST: This is the default method. Request body format:

        {
          "uuid": "6b48fbce-cd10-459c-b397-5673e4bbafaf",
          "assetName": "T1S03",
          "inputUrl": "https://storage.googleapis.com/T1S03.mp4"
          "username": "jonhdoe@epiclabs.io",
          "startDate": "2019-02-14T20:32:48.898Z",
          "endDate": "2019-02-14T20:43:11.825Z",
          "status": "finished",
          "errorMessage": undefined
        }
    • PUT: Request body:

        {
          "uuid": "6b48fbce-cd10-459c-b397-5673e4bbafaf",
          "assetName": "T1S03",
          "inputUrl": "https://storage.googleapis.com/T1S03.mp4"
          "username": "jonhdoe@epiclabs.io",
          "startDate": "2019-02-14T20:32:48.898Z",
          "endDate": "2019-02-14T20:43:11.825Z",
          "status": "finished",
          "errorMessage": undefined
        }
  • source: Optional field, its default value is 'lightflow'. When you are publishing an asset in LightFlow you can define which type of encoder you would like to use: use LightFlow encoder (the preffered method) or leverage any encoder resource that you already have (ex: Brightcove ZEncoder). These third party encoders tipically have their own callback mechanisms. With this field you can define which callbacks you would like to use, the ones raised by LightFlow or the ones raised by your encoder provider. Possible values:

    • lightflow: default option. Lightflow responsible of doing callbacks.
    • encoder: only applicable if client is using a third party encoder. LighFlow will pass callback information to the specified encoder, so the encoder will be one triggering the callback when encoding is done.
  • onSuccess: Optional field, its default value is 'true'. Defines in which cases the callback should be executed. Possible values:

    • true: callback is executed when the asset is published successfully.
    • false: callback won't be executed when the asset is published successfully.
  • on Failure: Optional field, its default value is 'true'. Defines in which cases the callback should be executed. Possible values:

    • true: callback is executed when there was an error while publishing the asset.
    • false: callback won't be executed when the asset could not be published due to any error.

Assets

Video optimization, content preparation and delivery. Generated video / audio assets ready to be streamed through Internet.

List assets

Returns history of assets.

Authorizations:
query Parameters
pageIndex
number

Pagination page index

pageSize
number

Pagination page size

creationDateFrom
ISO format date

Created date from filter

creationDateTo
ISO format date

Created date to filter

features
Comma-separated string values

Features filter (perceptual-quality, perceptual-quality-per-scene, content-moderation, archive-enrichment, taxonomy-classifier, face-recognition)

status
Comma-separated string values

Status filter (queued, running, error, finished, canceled)

inputUrlPath
string

Input URL filter

uuid
string

Asset UUID filter

name
string

Name filter

referenceId
string

Reference ID filter

tags
string

Tags filter

Responses

200

List of assets

401

Access token is missing or invalid

get /assets

Production API Url

https://api.lightflow.media//assets

Request samples

Copy
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
  
xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});
    
xhr.open('GET', '/assets');
xhr.setRequestHeader('Authorization', 'Bearer eyJh...');
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Content-Type', 'application/json');

xhr.send(data);

Response samples

application/json
Copy
Expand all Collapse all
{
  • "totalItems": 0,
  • "pageIndex": 0,
  • "pageSize": 0,
  • "pages": 0,
  • "items":
    [
    ]
}

Create an asset

Creates a new asset for video optimization or cognitive services.

Authorizations:
Request Body schema: application/json
description
string

Brief description of the asset (100 characters max).

parameters
object

Asset configuration.

callbacks
Array of objects

List of callbacks that will be used to notify when the asset processing task is done.

metadata
object

Asset metadata.

Responses

200

Created asset

401

Access token is missing or invalid

post /assets

Production API Url

https://api.lightflow.media//assets

Request samples

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "parameters":
    {
    },
  • "callbacks":
    [
    ],
  • "metadata":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "uuid": "string",
  • "username": "string",
  • "accountName": "string",
  • "creationDate": "2019-05-15",
  • "status": "string",
  • "stage": "string",
  • "priority": 0,
  • "parameters":
    {
    },
  • "callbacks":
    [
    ],
  • "playbackManifests":
    [
    ],
  • "metadata":
    {
    }
}

Retrieve an asset

Returns the asset whose id is equal to {uuid}.

Authorizations:
path Parameters
uuid
required
string

Identifier of the asset to be retrieved.

Responses

200

Asset

401

Access token is missing or invalid

404

Asset not found

get /assets/{uuid}

Production API Url

https://api.lightflow.media//assets/{uuid}

Request samples

Copy
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
  
xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});
    
xhr.open('GET', '/assets/zdixr');
xhr.setRequestHeader('Authorization', 'Bearer eyJh...');
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Content-Type', 'application/json');

xhr.send(data);

Response samples

application/json
Copy
Expand all Collapse all
{
  • "uuid": "string",
  • "username": "string",
  • "accountName": "string",
  • "creationDate": "2019-05-15",
  • "status": "string",
  • "stage": "string",
  • "priority": 0,
  • "parameters":
    {