Beamr Cloud Rest API v1.1.1

Beamr Cloud Rest API v1.1.1

Beamr Cloud Rest API v1.1.1

Introduction

The Beamr Video cloud service runs on the Amazon AWS infrastructure, and is accessible via REST API.
This document outlines the supported formats, APIs and usage limitations for the Beamr Video cloud service.

Supported Formats

Input formats


  • Containers: MP4, MOV

  • Video Codecs: H.264, HEVC

  • Audio Codecs: Any (pass through) 


Output formats

  • Containers: MP4, MOV

  • Video Codecs: H.264, HEVC

  • Audio Codecs: Any (pass through)


Unsupported in v1


  • Files with multiple video tracks

  • Interlaced video content

  • Fragmented MP4 files

Limitations

Maximum video resolution: 4K

Maximum video file size: 1GB

Processing flow

The source files can be provided using HTTP(s). . 

The output files are stored in an S3 bucket owned by Beamr, and accessible by the user. 


The user notifies Beamr of each file that requires optimization using an API call. 


The Beamr service processes the file, places the result in the output S3 bucket, and notifies the user that the file is ready using a messaging service (HTTP POST). 


The user can then copy the file from the output bucket to their own bucket.  The files are deleted from the output bucket after 7 days, or via a specific API call.

Usage Overview

To submit jobs, the user sends a POST message to the server with the source URL of the input video file.  


After the job is submitted, you can view the status by querying on the "location" URL returned from the server. 


To download the output video file, GET the optimizedFileUrl returned in the API response. The server will redirect to a signed-url of the file, which is valid for 5 minutes.  You can then use the signed-url to download the file.

Prerequisites

  1. Sign in/up to cloud.beamr.com go to cloud.beamr.com/api and Create your API Access Token

  2. Authentication is required for all methods (Implemented using access tokens)

API Overview

Basic entities

  1. Jobs

API Endpoint

  • Base URL: https://api.beamrvideo.com/v1/

  • All traffic is sent using https

  • Responses are formatted in json

  • Each request must include authentication credentials, which should be provided in the HTTP header

Jobs

A Job is an optimization task for a specific file.  Jobs are submitted to the Beamr service using the API. During processing, and upon completion, notifications are sent to the job submitter. Job status and data are kept for 24 hours, after which the data is deleted, and the job-record (meta-data) is archived.

API Methods

1. Submitting a new job

Required parameters:

source - url to source file. Supported formats




Request Example

{

  "source": "https://example.com/sample.mov?Signature=Uvjxp4bq81Yp5wEi63hzgcizBM8%3D&Expires=1486916931174&AWSAccessKeyId=AKIAI25VAYVHFO2VH6UA",

}

Response

{

    "code": 201, 

    "id": "fDvRHvMoRYWSjWTyMr9FW3", 

    "info": {

        "created": 1486916931174, 

        "source": 

"https://example.com/sample.mov?Signature=Uvjxp4bq81Yp5wEi63hzgcizBM8%3D&Expires=1486916931174&AWSAccessKeyId=AKIAI25VAYVHFO2VH6UA", 

        "status": "pending"

    }, 

    "location": "https://api.beamrvideo.com/v1/jobs/fDvRHvMoRYWSjWTyMr9FW3", 

    "status": "CREATED"

}

3. Querying job status

GET https://api.beamrvideo.com/v1/jobs/job-id


Successful job response:

{

    "code": 200, 

    "job": {

        "id": "iHK5Pdrjw9aCYhwEEcNETV", 

        "info": {

            "created": 1486916931174, 

            "fileCompressionRatio": 2.14, 

            "fileSavings": 53.19, 

            "optimizedVideo": "s3://beamr-bv-cloud-us-east-1-results/iHK5Pdrjw9aCYhwEEcNETV/sample.mov", 

            "optimizedVideoUrl": "https://api.beamrvideo.com/v1/jobs/iHK5Pdrjw9aCYhwEEcNETV/optimized_video", 

            "source": "https://example.com/sample.mov?Signature=Uvjxp4bq81Yp5wEi63hzgcizBM8%3D&Expires=1486916931174&AWSAccessKeyId=AKIAI25VAYVHFO2VH6UA", 

            "status": "completed", 

            "videoCompressionRatio": 2.18, 

            "videoSavings": 54.23, 

        }, 

        "location": "https://api.beamrvideo.com/v1/jobs/iHK5Pdrjw9aCYhwEEcNETV"

    }, 

    "status": "OK"

}

Failed job response

{

  "status": "ok",

  "code": "200",

  "jobs": [

        {

            "id": "iHK5Pdrjw9aCYhwEEcNETV", 

            "info": {

                "created": 1486916931174,

                "fileCompressionRatio": 2.14, 

                "fileSavings": 53.19, 

                "optimizedVideo": "s3://beamr-bv-cloud-us-east-1-results/iHK5Pdrjw9aCYhwEEcNETV/sample.mov", 

                "optimizedVideoUrl": "https://api.beamrvideo.com/v1/jobs/iHK5Pdrjw9aCYhwEEcNETV/optimized_video", 

                "source": "https://example.com/sample.mov?Signature=Uvjxp4bq81Yp5wEi63hzgcizBM8%3D&Expires=1486916931174&AWSAccessKeyId=AKIAI25VAYVHFO2VH6UA", 

                "status": "completed", 

                "videoCompressionRatio": 2.18, 

                "videoSavings": 54.23, 

            }, 

            "location": "https://api.beamrvideo.com/v1/jobs/iHK5Pdrjw9aCYhwEEcNETV"

        },

     …

  ]

}

  1.  Retrieving the results file

GET https://api.beamrvideo.com/v1/jobs/job-id/optimized_video



The server will redirect the client (response code 302) to the optimized file.




5. Requesting removal of a completed job, or cancellation of in-progress job

DELETE https://api.beamrvideo.com/v1/jobs/job-id

Response

{

  "status": "ok",

  "code": "200",

}

Authentication

  • Required for all methods

  • Implemented using bearer access tokens (see prerequisites above)

Job status

  • pending

  • processing

  • completed

  • error

Error Codes

  • pending

  • processing

  • completed

  • error

Using the API from the command line

A convenient way to submit jobs to the Beamr Video Cloud API is through a REST command line utility such as httpie or curl.

For example, to create a job

https -A Bearer -a <token> POST https://api.beamrvideo.com/v1/jobs source="https://example.com/bird.mp4" 

To query the status of a job

http -A Bearer -a <token> GET https://api.beamrvideo.com/v1/jobs/Qrj2TtmfAAKF7ZPN55GLqe

To download the optimized file

http -A Bearer -a <token> -d GET https://api.beamrvideo.com/v1/jobs/Qrj2TtmfAAKF7ZPN55GLqe/optimized_video