Prerequisites

To incorporate Beamr into your pipeline using API, you should first:

Signup to Beamr cloud to
Configure an API workflow with the required encoding configuration
Grant Beamr permissions to read/write content using our one of our available storage integrations.

If our current storage integration do not cover your needs, custom solutions are also available. Please contact our sales.

API Tutorial

This tutorial shows how you can use the Beamr Cloud API, for optimizing and/or resizing your own video files.

The examples here use the HTTPie command-line tool for sending the HTTP requests to the API, but you can use any tool or platform you prefer.

Get your API Token

All requests to the API must contain an API Token in the request's "Authorization" header.
Go to the API page, and your API token should appear after a few seconds. Copy and save it somewhere safe:

Get the Workflow ID

To use the API, you will need to know the Workflow ID for the optimization you want to perform.

Create a workflow of type "API":

Then copy the workflow's ID:

Optimize a video

For the API to access your video, it needs to be accessible with a http(s):// URL, or with an s3:// URL pointing to the file in an AWS S3 bucket.

To create a new optimization job, send a POST request to the API's /jobs route:

http POST https://api.beamr.com/v1/jobs \
  Authorization:<YOUR_API_TOKEN> \
  source="https://example.com/video.mp4" \
  workflowId="<YOUR_WORKFLOW_ID>"

You should receive a response similar to:

{
  "jobIds": ["b3f4f4be-7b23-43e3-b306-6deed367d45d"],
  "locations": ["https://api.beamr.com/v1/jobs/b3f4f4be-7b23-43e3-b306-6deed367d45d"],
  "source": "https://example.com/video.mp4",
  "timestamp": 1692543236.8233376,
  "timestampHuman": "2023-08-20T14:53:56.823"
}

The jobId value in the response is the unique ID for the new job you've created.

You will need it for checking your job's status, and for downloading the result.

Job status notifications to your callback URL

You can receive notifications about your job's status by providing a callback_url field in the request:

http POST https://api.beamr.com/v1/jobs \
  Authorization:<YOUR_API_TOKEN> \
  source="https://example.com/video.mp4" \
  workflowId="<YOUR_WORKFLOW_ID>" \
  callback_url="https://your-server.com/job-status-callback"

Then when the job is complete, you will receive a request to the provided callback_url with a JSON-formatted body containing the job ID and a SUCCEEDED or FAILED status:

{
  "job_id": "b3f4f4be-7b23-43e3-b306-6deed367d45d",
  "status": "SUCCEEDED"
}

Check optimization status

To check if your optimization is complete or has failed, send a GET request to the /jobs/<jobId> route.

Replace <jobId> with the jobId that you got when submitting the job:

http GET https://api.beamr.com/v1/jobs/7e3bec34-a64a-4f41-8f5e-e52c36a8688c \
  Authorization:<YOUR_API_TOKEN>

Example response for a successful job:

{
  "job": {
    "jobId": "7e3bec34-a64a-4f41-8f5e-e52c36a8688c",
    "input": {"filesize": 6520041, "path": "https://example.com/video.mp4"},
    "output": {"filesize": 2626378, "savings": 59.72},
    "owner": "demo",
    "status": "SUCCEEDED",
    "created": 1692538444.0,
    "createdHuman": "2023-08-20T13:34:04.000",
    "lastUpdate": 1692538561.0,
    "lastUpdateHuman": "2023-08-20T13:36:01",
    "ttl": 1693143361.0,
    "ttlHuman": "2023-08-27T13:36:01.000"
  }
}

For a failed job, the status will be FAILED.

A status of PENDING or RUNNABLE means the job has not started processing yet.

Download optimized video

When your job has completed successfully, you can download the result video file by sending a GET request to the /jobs/<jobId>/download route.

Replace <jobId> with the job's ID that you got previously.

http GET https://api.beamr.com/v1/jobs/7e3bec34-a64a-4f41-8f5e-e52c36a8688c/download \
  Authorization:<YOUR_API_TOKEN>

The response will redirect the client to a URL for downloading the result - most clients will follow the redirect automatically, so you will typically not need to worry about this.

API integration