Using Video Transcoding API

Video Transcoding API How To

Listing Available Providers

$ curl -X GET http://api.host.com/providers

[
  "elastictranscoder",
  "elementalconductor",
  "encodingcom"
]

Getting Provider Capabilities and Details

$ curl -X GET http://api.host.com/providers/encodingcom

{
  "capabilities": {
    "destinations": ["akamai", "s3"],
    "input": ["prores", "h264"],
    "output": ["mp4", "hls", "webm"]
  },
  "enabled": true,
  "health": {"ok": true},
  "name": "encodingcom"
}

Creating a Preset

Given a JSON file called preset.json:

{
  "providers": ["elastictranscoder", "elementalconductor", "encodingcom"],
  "preset": {
    "name": "Preset_Test",
    "description": "This is an example preset",
    "container": "m3u8",
    "profile": "Main",
    "profileLevel": "3.1",
    "rateControl": "VBR",
    "video": {
        "height": "720", 
        "width": "1080", 
        "codec": "h264",
        "bitrate": "1000000",
        "gopSize": "90",
        "gopMode": "fixed",
        "interlaceMode": "progressive"
    },
    "audio": {
        "codec": "aac",
        "bitrate": "64000"
    } 
  }
}

The Encoding API will try to create the preset in all providers described on the providers field. It will also create a PresetMap registry on Redis, which is a map for all the provider's PresetIDs.

You can just set width or height instead of both if you want to maintain source's aspect ratio.

$ curl -X POST -d @preset.json http://api.host.com/presets

{
  "PresetMap": "Preset_Test",
  "Results": {
    "elastictranscoder": {
      "Error": "",
      "PresetID": "1459293696042-8p8hak"
    },
    "elementalconductor": {
      "Error": "",
      "PresetID": "Preset_Test"
    },
    "encodingcom": {
      "Error": "creating preset: CreatePreset is not implemented in Encoding.com provider",
      "PresetID": ""
    }
  }
}

Creating a PresetMap

Some providers like Encoding.com don't support preset creation through the API. The alternative is to create the preset manually on the provider's control panel and associate it with the Encoding API by creating a PresetMap.

$ curl -XPOST -d '{"name":"preset_name", "providerMapping": {"encodingcom": "preset_id",
"output": {"extension": "ts"}}' http://api.host.com/presetmaps

Listing PresetMaps

$ curl -X GET http://api.host.com/presetmaps

{
  "nyt_preset": {
    "name": "nyt_preset",
    "output": {
      "extension": "ts"
    },
    "providerMapping": {
      "encodingcom": "preset_manual_id"
    }
  },
  "preset-1": {
    "name": "preset-1",
    "output": {
      "extension": "mp4"
    },
    "providerMapping": {
      "elastictranscoder": "1281742-93939",
      "elementalconductor": "abc123"
    }
  }
}

Deleting PresetMap

$  curl -X DELETE http://api.host.com/presetmaps/preset-1

Creating a Job

To create a job you need to specify a few required parameters: one or more preset, a provider, a video source. Additionally, there are optional parameters such as: callback URLs that notifies the transcoding progress and completion of the job and streaming parameters in case you want to create Adaptive Streamings outputs (HLS, DASH)

See an example below for job.json:

{
  "presets": ["preset_1", "preset_2"],
  "provider": "encodingcom",
  "source": "http://nytimes.com/BickBuckBunny.mov?nocopy",
  "statusCallbackInterval": 5,
  "statusCallbackURL": "http://callback.server.com/status",
  "completionCallbackURL": "http://callback.server.com/done",
  "streamingParams": {
    "SegmentDuration": 10,
    "Protocol": "hls"
  }
}

Then, make a POST request to the API:

$ curl -X POST -H "Content-Type: application/json" -d @job.json  http://api.host.com/jobs

{"jobId":"95e1ebbd6330f2b3"}

It's important to note that your callback server should be able to handle POST requests from the API.

Getting Job Details

With the jobId returned by job creation:

$ curl -X GET http://api.host.com/jobs/95e1ebbd6330f2b3

{
  "outputDestination": "s3://output-bucket",
  "providerJobId": "114",
  "providerName": "elementalconductor",
  "providerStatus": {
    "pct_complete": "0",
    "status": "pending",
    "submitted": "2016-03-31T22:01:16Z"
  },
  "status": "queued"
}