LightFlow API documentation (2.0.1)

Download OpenAPI specification:Download

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Introduction

LightFlow is a video platform that leverages the use of artificial intelligence to optimize the quality of your videos at the most effective bitrate. LightFlow is API driven and can be easily integrated in your current media workflow with a few API calls.

Get an API token

LightFlow API uses a token for authentication. A default token is generated automatically for every new user. The token can be regenerated in the Settings section of the LightFlow portal.

Token generation view

Publish an asset

An asset is a video, including the output formats used to watch it online and offline, and the set of optimizations applied to maximize the viewers quality of experience. To publish an asset, send a POST to the /assets endpoint:

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
          }
        }
      }
    }'

In the example above, an optimized version of "your-video.mp4" is published, ready to be delivered as MP4 file and HLS and MPEG-DASH streams.

Watch the video

As soon as the status of the asset changes to "finished", the video is ready for playback. The status of the assets can be monitored using callbacks. See the [Using Callbacks] (https://dashboard.lightflow.media/documentation.html#tag/Using-Callbacks) section for further information. To play back the video, create a playback URL using the asset uuid and open the URL in your preferred browser


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

Alternatively the video can be watched in the View Asset section of the LightFlow portal, together with an analyis of the video output quality, by clicking on the view icon in the list of assets in the LightFlow portal LightFlow portal.

API call 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"
}

Asset processing errors

Asset object provides information on processing error. Example

{
  ...
  "assetError": {
    "code": 2404,
    "message": "Error downloading input file: remote server returned HTTP 404"
  }
  ...
}

Error codes list

General errors

  • 1001: Unknown error
  • 1002: Error on asset creation
  • 1003: Error on asset processing

Storage errors

  • 2001: Error downloading input file
  • 2002: Error downloading input file: could not connect to remote server
  • 2003: Input file is invalid or corrupt
  • 2004: Input file bitrate exceeds the allowed limit for trial accounts
  • 2005: Input file duration exceeds the allowed limit for trial accounts
  • 2006: Input file format is not valid for 4K: asset has a width below 2560 pixels
  • 2007: Storage credentials error
  • 24XX: Range (2400-24XX). Represents HTTP 4XX error returned by remote server while attempting to download the input file:
    • 2401: Unathorized (please review your bucket credentials)
    • 2403: Forbidden (your user have not access to the resource)
    • 2404: Not found (the resource does not exist)
    • 2429: Too many requests (the external service is overloaded, try again later)
  • 25XX: Range (2500-25XX). Represents HTTP 5XX error returned by remote server while attempting to download the input file:
    • 2500: Remote server problem (the external service is not responding, try again later or contact support)
    • 2503: Service unavailable (trythe external service is not responding, again later or contact support)
    • 2504: Gateway timeout (the external service is not responding, try again later or contact support)
  • 2070: Error downloading subtitles

Brightcove errors

  • 3001: Error connecting to Brightcove
  • 3002: Brightcove encoder: input file is invalid or corrupt
  • 3003: Reference Id assigned to this asset is already in use and could not be published in Brightcove
  • 3004: Brightcove encoder: Error creating the encoding profile for this asset
  • 3005: Error publishing asset on Brightcove

Packaging/Uploading errors

  • 4001: Error uploading MP4 result files
  • 4002: Error uploading DASH result files
  • 4003: Error uploading HLS result files
  • 4004: Error connecting to upload server
  • 4013: Error uploading thumbnails
  • 4014: Error stitching video chunks
  • 4005: Unknown error preparing/uploading output files

Protection errors

  • 2050: EZDRM response is not the expected
  • 2051: EZDRM request timed out
  • 2052: EZDRM request has too many redirects
  • 2053: EZDRM returned a general http error
  • 2054: EZDRM general resquest error
  • 2055: EZDRM request returned internal server error
  • 2060: Irdeto response is not the expected
  • 2061: Irdeto request timed out
  • 2062: Irdeto request has too many redirects
  • 2063: Irdeto returned a general http error
  • 2064: Irdeto general resquest error
  • 2065: Irdeto request returned internal server error
  • 2066: DRM protection not selected

Inference errors

  • 6001: Error uploading inference results

LightFlow encoder errors

  • 7001: Error encoding input

Supported video 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)

Supported Input/Output storage

LightFlow supports a wide variety of input and output storage types. If you don't see your storage solution here, please contact Lightflow support for assistance.

Input & Output

To create an storage location as source/destination of videos for Lightflow, send a POST request to the /inputs-outputs endpoint. 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. Click on the links above for guides to configure specific storage types.

Supported Encoders