Whether you're looking to offload a set of simple ffmpeg processes, optimize existing proprietary media workflows, or automate unbounded scalability to your existing CMS, MAM or other asset management platform, Encoding.com's API has been purpose-built to support a massive amount of traditional and bespoke media processing functions. Our team works to standardize the integration of over 40 professionally maintained encoding engines for all your media processing needs, including decoding, content aware transcoding, broadcast, camera and edit codecs, transforms, Dolby audio processing, image transformation, closed captions, programmatic editing, adaptive bitrate packaging, ad breaks, HDR, watermarking, and digital rights management. Whether you have a few assets a month, or a million a month, the API stands ready to tackle any workload with ultra fast processing times with our Technology & Engineering Emmy® award winning split and stitch architecture, Ludicrous mode.
The API is designed to have users make a minimum of requests (often a single request) to take an asset from any source location, provide desired transforms, transcoding and packaging, and deliver it securely to the destination(s) of choice. This is accomplished through the use of declarative XML or JSON requests that declare the desired action to take. This matches the style of job requests most often seen in the broadcast industry, meeting the use case of "take these things, perform these changes, and put the results here" in as few calls as possible. With just one call, you'll be able to perform even complex, multi-step workflows, generate or re-use intermediates to be used in subsequent requests, and quickly understand by looking at a single document all of the actions that were requested or applied in the job request. We feel this approach more closely resembles the needs of video engineers and workflow engineers who rely on a job-centric model of processing, versus a model where each job request ends up spanning tens or hundreds of individual calls to name assets, transforms, destinations, and then track progress.
For those users who would like more fine-grained control over each of the steps of processing, there are also separate actions available for subsets of a job request, e.g. identifying source media assets, introspecting metadata on them, performing transforms and storing intermediates, final packaging and delivery, and automated quality control (QC) including both Interra's Baton Validation and Telestream's Qualify QC Validation verifications.
This functionality is paired with a robust notification system that can both proactively notify via email, webhook, and/or message queue, as well as be interrogated during processing to determine status or terminate an action underway.
Now, let's cover the basics of getting started with the API.
1. Register
First things first, you're going to need an account. You can use our own authentication system, or use Okta SSO to connect via a SAML provider.
To register, just create a new Developer account. New accounts include API access credentials, 1 GB of free encoding bandwidth per month, and access to nearly all of our powerful features. Usage rates apply to Vid.ly usage and some premium features.
If you're looking to integrate via Okta, you first need to register a master account native to our system as per above, then add Encoding.com to your integrations from this marketplace url. Once that's done you can provide access to your Okta users through our sub-account management API or management UI.
Once you're ready to scale up cloud media workflows, simply log in to the Encoding.com Client Interface and select one of the Monthly or Pre-Pay plans to meet your projected encoding volumes and SLA requirements. High-volume users should connect directly with us for custom plans. All of our plans are designed to scale with your needs.
2. Build and Post
Interactions with the Encoding.com API are received by HTTPS POST requests to our workflow processing API. Users can choose a number of actions, but the primary two actions we tend to see are requests to use preset-based actions, or requests that explicitly lay out all the actions to be taken to process an asset. The steps to make any request of the platform are the same:
- Prepare a job request as either an XML or JSON text file or blob.
- Submit the request with the XML or JSON to the API.
- Use a subsequent API request, web interface, or notification callbacks to monitor the status of the request.
Optional: Use an encoding preset
Utilize one of our expert-designed web, CableLabs, mobile, or set-top box pre-defined presets, or build a repeatable workflow via an API call and save your own custom profile as a custom output preset. Presets are a great way to get started if you know your target devices or codecs but aren't certain of the best parameters to use to get optimized outputs.
Build your XML or JSON template
There are several ways to create your first API request:
Copy the XML or JSON from our web interface request generator, or code from scratch using one of our sample templates:
- A typical MP4 request as a template.
- A typical HLS request as a template.
- Comprehensive XML and JSON examples.
Post and Go
Send your XML/JSON template to our API endpoint via an HTTPS POST. Or, use our browser-based XML/JSON submission tool to verify and test your XML/JSON without writing a single line of code.
3. Integrate
Accelerate your development
For quick one-offs, many developers start with a flat XML or JSON file, and use curl to start testing.
We have API wrappers for several popular languages:
- Python
- Ruby
- Java
- PHP
- .NET
- Zend
- ColdFusion,
- VBS
Design your workflow
Workflows that already have metadata of their source(s) can utilize our AddMedia action to immediately begin processing of the job request. Alternatively, the AddMediaBenchmark action will return the output of MediaInfo for the asset which your orchestration system can review prior to a Process Media action request.
Provide a webhook endpoint or queue topic to your API request to receive and parse our notification callbacks. These notify your orchestration system with a detailed report when jobs are complete.
For adaptive bitrate workflows, look to our Adaptive Intermediate Workflow to separate transcoding and packaging in your workflow. Send one API request to encode your TS or fMP4 bitrate ladder, and then a second API request to package into adaptive packages like DASH and HLS.
Browser video upload system (UGV)
Enable end users to upload videos directly to Encoding.com. Use our out-of-the-box PHP or .NET code that includes API integration, browser-based upload functions, a progress bar, notifications and cloud storage.