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
Sign in/up to cloud.beamr.com go to cloud.beamr.com/api and Create your API Access Token
Authentication is required for all methods (Implemented using access tokens)
API Overview
Basic entities
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"
},
…
]
}
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
