NAV
     

VOD Encoder API

Welcome to the VOD Encoder REST API documents. You can use this API to manage your video encoding jobs, monitor status and integrate with your apps.

All API requests are authenticated with MCP-TOKEN authentication. See Authentication API documentation for obtaining an access token.

Quick Start

    curl -X POST https://encoding.apis.anvato.net/job \      -H "Authorization: MCP-TOKEN token=<api-token>" \      -H "Content-Type: application/json" \      -d '{      "input": "https://anvato-test-media.storage.googleapis.com/sample.mp4"      }'

Now that you have the basic encoding working, your optional next steps are:

Read on for details.

Concepts

Authentication

You can use token based or API key based authentication. All of the examples here are token based, to generate the API key versions you simply replace the Authorization header with the API key based one as explained below.

Tokens

You can use your Anvato login/password and generate a token from the authentication API. Then use it as -H "Authorization: MCP-TOKEN token=<api-token>"

API Keys

If you do not have an Anvato login, you can obtain API Keys and use them with the standard HTTP basic authentication, i.e., -H "Authorization: Basic <base64-encoded-apikeys>"));

where <base64-encoded-apikeys> = base64encode("<your-public-key>:<your-private-key>")

Most libraries support this out of the box. e.g., curl -u "your-public-key:your-private-key" https://...

Job

Each encoding request is specified by a job object. A job can contain a fully inlined specification for fine grain control over the encoding job. Alternatively, it can refer to pre-created profiles, or use defaults.

A job is composed of the following sub parts, most of which are optional

Each sub-part - except the input - can be fully specified inline or can be specified by reference. A reference implies the subpart was created separately using the REST APIs and referred using the assigned ID.

Inputs

Input of a job is an ordered array of media objects. Each media object is defined by its url and optionally start time and duration.

Encoding profiles

An encoding profile specifies the low-level encoding parameters, such as codec, bitrate, resolution, sampling rate, sample format and more. A job object can specify an inline profile or may separately generate profile ids and use the ids instead.

Overlays

Overlay objects are images (typically a PNG with alpha channel) with url, start, duration, position and size information that are overlaid on top of the output video. You can specify more than one overlay objects for the same output.

Outputs

Outputs specify the codec and destination information. If the encoding profiles are identical we perform a single-encode-multiple-mux, which means we will encode once and package multiple times based on the same encoded content. This is beneficial for you as you do not pay for the extra muxings.

Branding profiles

A branding profile specifies the pre-roll, trailer and overlay image details.

Encoding Profile

{
    "name" : "My website profile",
    "encodes" : [
        {
            "video.bitrate" : 1200000,
            "video.width" : 960,
            "video.height" : 540,
            "video.codec" : "h264",
            "video.profile" : "high",
            "audio.codec" : "aac",
            "audio.bitrate": 64000
        },
        {
            "video.bitrate" : 600000,
            "video.width" : 640,
            "video.height" : 360,
            "video.codec" : "h264",
            "video.profile" : "high",
            "audio.codec" : "aac",
            "audio.bitrate": 64000
        }
    ],
    "formats" : [
        {
            "type" : "hls",
            "version" : "3",
        },
        {
            "type" : "dash"
        }
    ]
}

Encoding profile object defines the encoding parameters for codecs and output formats.

These are the supported video codec parameters.

Key Description
video.width Width of the output image. Can be empty or 0. See below for details.
video.height Height of the output image. Can be empty or 0. See below for details.
video.bitrate Output video bitrate in terms of bits per second.
video.codec Output video codec
video.fitting (optional) The fitting method to use in case of both width and height are specified. See below for details.
video.embedded_caption (optional) true or false. Enable/disable caption embedding in output file. For example, this flag enables embedding of 608/708 captions in H264 SEI packets.
video.pixel_format (optional) Pixel format, can be one of yuv420p, yuv422p
video.gop_size (optional) GOP frame count.
video.profile (optional) Codec profile. Can be baseline, main or high
video.bframes (optional) Specify the consecutive b-frames in the GOP structure for main and high profiles. Possible values are 0 (default), 1, 2 and 3.

These are the supported audio codec parameters.

Key Description
audio.bitrate Output audio bitrate in terms of bits per second.
audio.codec Output audio codec
audio.profile Audio codec profile. Can be HE or LC
audio.channels Audio channel count. Must be one of 2, 6 or 8.
audio.sample_format Audio sample format.
audio.sample_rate Sampling rate, defaults to 44100

These are the supported format parameters

Key Description
type Type of packaging, such as HLS or MPEG-DASH
version Version of the packaging protocol (e.g., HLS version 3)
packager For HLS, this can be ts or fmp4
fragment_duration Duration of each fragment in seconds.

Video Codecs

The following video codecs are supported:

Audio Codecs

The following audio codecs are supported:

Formats

Output Sizing and Aspect Ratios

width and height of the output can be 0 or left empty. In that case the following logic applies:

List all Encoding Profiles

This endpoint retrieves all encoding profiles.

Try now

Endpoint

GET /latest/encode-profile

Query Parameters

Parameter Default Description
page_no 0 0 based page number.
page_sz 20 Number of items in the requested page.

Create or Update an Encoding Profile

The following example creates two renditions, one 720p and other 360p. Each rendition is then packaged and stored as HLS and DASH

curl -X POST "https://encoding.apis.anvato.net/latest/encode-profile/[ID]" \
  -H "Authorization: MCP-TOKEN token=your-access-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"My encode profile",
    "encodes" : [ 
        {
            "video.codec": "h264",
            "video.bitrate": 2500000,
            "video.height": 720,
            "audio.codec": "aac",
            "audio.bitrate": 64000
        },
        {
            "video.codec": "h264",
            "video.bitrate": 1200000,
            "video.height": 360,
            "audio.codec": "aac",
            "audio.bitrate": 64000
        }
    ],
    "formats" : [ 
        {
            "type": "hls"
        },
        {
            "type": "dash"
        } 
    ]
  }'

This endpoint creates an encoding profile, or updates the profile if ID is specified. You must post a form with the following fields:

Try now

Endpoint

POST /latest/encode-profile/<ID>

Response

HTTP 2XX and ID {      "id" : "f46d0460-4f88-4b5f-9cc5-65201fa72f5d", }

Delete an Encoding Profile

curl -X DELETE "https://encoding.apis.anvato.net/latest/encode-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key" \

This endpoint deletes an encoding profile. Deleting an encoding profile while there are pending existing encoding tasks will result in those tasks falling into error status.

Try now

Endpoint

DELETE /encode-profile/<ID>

Get a Specific Encoding Profile

curl "https://encoding.apis.anvato.net/latest/encode-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key"

The above command returns JSON structured like this:

{
    "id" : "0c345c35-4fc2-4eb2-a93d-d4671579fcfd",
    "name" : "My encode profile",
    "encodes":
    [   
        {
            "width" : 640,
            "height" : 360,
            "video_codec" : "h264",
            "audio_codec" : "aac",
            "video_bitrate" : 1200000,
            "audio_bitrate" : 64000
        },
        {
            "width" : 960,
            "height" : 540,
            "video_codec" : "h264",
            "audio_codec" : "aac",
            "video_bitrate" : 1800000,
            "audio_bitrate" : 64000
        },
    ],
    "formats":
    [
        {
            "type" : "hls"
        },
        {
            "type" : "dash"
        }
    ]
}

This endpoint retrieves a specific encoding profile.

Try now

Endpoint

GET /encode-profile/<ID>

DRM Profile

List all DRM Profiles

This endpoint retrieves all DRM profiles.

Try now

Endpoint

GET /latest/drm-profile

Query Parameters

Parameter Default Description
page_no 0 0 based page number.
page_sz 20 Number of items in the requested page.

Create or Update a DRM Profile

curl -X POST "https://encoding.apis.anvato.net/latest/drm-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key" \
  -d '{ \
  "name" : "My drm profile", \
  "vendors" : { ... \
  }'

This endpoint creates a DRM profile, or updates the profile if ID is specified. You must post a JSON as the payload of the request.

Following are the JSON fields.

Try now

Endpoint

POST /latest/drm-profile/<ID>

Response

HTTP 2XX and ID {      "id" : "f46d0460-4f88-4b5f-9cc5-65201fa72f5d", }

Delete a DRM Profile

curl -X DELETE "https://encoding.apis.anvato.net/latest/drm-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key" \

This endpoint deletes a DRM profile. Deleting a DRM profile while there are pending existing encoding tasks will result in those tasks falling into error status.

Try now

Endpoint

DELETE /drm-profile/<ID>

Get a Specific DRM Profile

curl "https://encoding.apis.anvato.net/latest/drm-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key"

The above command returns JSON structured like this:

{
    "id" : "0c345c35-4fc2-4eb2-a93d-d4671579fcfd",
    "name" : "My drm profile",
    "vendors": {
        "playready" : {
            "key_server_url" : ""
        },
        "widevine" : {
            "key_server_url" : ""
        },
        "fairplay" : {
            "key_server_url" : ""
        }
    }
}

This endpoint retrieves a specific DRM profile.

Try now

Endpoint

GET /drm-profile/<ID>

Branding Profile

Sample branding profile

{
    "name" : "My branding profile",
    "bumpers": [
        {
            "url": "http://server.com/pre1.mp4"
        },
        {
            "url": "http://server.com/pre2.mp4"
        }
    ],
    "trailers": [
        {
            "url": "http://server.com/trail1.mp4"
        },
        {
            "url": "http://server.com/trail2.mp4"
        }
    ],
    "overlays": [
        {
            "url" : "http://server.com/trail1.mp4",
            "start" : 5.0,
            "duration" : 5.0,
            "position" : "bottom-right"
        }
    ],
}

Branding profiles provide an easy way to specify prerolls, trailers and overlays to your videos.

Following fields are supported:

Bumper

Sample bumper

{
    "url" : "http://example.com/video.mp4",
    "start" : 3.0
}

Following fields apply to a bumper object

Trailer

Sample trailer

{
    "url" : "http://example.com/video.mp4",
    "start" : 3.0
}

Following fields apply to a bumper object

Overlay

Sample overlay

{
    "url" : "http://example.com/iamge.png",
    "width" : 64,
    "height" : 64,
    "position" : "bottom-right"
}

Following fields apply to an overlay object

List all Branding Profiles

This endpoint retrieves all branding profiles.

Try now

Endpoint

GET /latest/branding-profile

Query Parameters

Parameter Default Description
page_no 0 0 based page number.
page_sz 20 Number of items in the requested page.

Create or Update a Branding Profile

The following example creates a branding profile with one bumper, two trailers and an overlay image at the bottom right.

curl -X POST "https://encoding.apis.anvato.net/latest/branding-profile/ID" \
  -H "Authorization: MCP-TOKEN token=your-access-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My branding profile",
    "bumpers": [ {
        "url": "http://example.com/bumper.mp4"
    } ],
    "trailers" : [ {
        "url": "http://example.com/trailer1.mp4"
    }, {
        "url": "http://example.com/trailer2.mp4"
    } ],
    "overlays" : [ {
        "url": "https://example.com/olay.png",
        "position": "bottom-right"
    } ]
  }'

This endpoint creates an encoding profile, or updates the profile if ID is specified. You must post a form with the following fields:

Try now

Endpoint

POST /latest/branding-profile/<ID>

Response

HTTP 2XX and ID {      "id" : "f46d0460-4f88-4b5f-9cc5-65201fa72f5d", }

Delete a Branding Profile

curl -X DELETE "https://encoding.apis.anvato.net/latest/branding-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key" \

This endpoint deletes a branding profile. Deleting a branding profile while there are pending existing encoding tasks will result in those tasks falling into error status.

Try now

Endpoint

DELETE /branding-profile/<ID>

Get a Specific Branding Profile

curl "https://encoding.apis.anvato.net/latest/branding-profile/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint retrieves a specific branding profile.

Try now

Endpoint

GET /branding-profile/<ID>

Job

The VOD encoding API works on job objects. Each job may have one or more input assets and one or more output assets.

Following are the fields of a job.

name (optional) Title of the job. This is for your bookkeeping purposes only. This field is also provided in the name field of the list job API.
input (string or Object). Input video object or a url.
state (read-only) Current state of the job. Can be one of pending, processing, success, error or cancelled.
encode_profile_id The reference to the encoding profile. If you specify a profile id, you cannot use inlined output.
branding_profile_id (optional) The reference to the branding profile.
drm_profile_id (optional) The reference to the DRM profile.
progress (read-only) Percent progress of the job.
output (string). The URL of the folder where the encoded renditions will be stored.

Input

Input can be a string or an object. A string specifies the mezzanine video url only and sets the other optional parameters to default values.

Following are the fields of an input object.

url URL of input video file. Supported input protocols are http, ftp, sftp, gcs and s3.
private_key (optional) The private keyfile in case the url protocol requires key based access, such as sftp
audio_map (optional) An array mapping the audio structure to output. See below for details.
begin (optional) Begin timestamp of the desired part in video file. If not specified, encoder starts from the beginning of the file.
end (optional) End timestamp of the desired part in video file. If not specified, encoder ends at the end of the shortedst stream in the file.
adbreaks[] (optional) Array of adbreak objects that specify the adbreak locations. If the ads also burned in/included in the file, you can also specify the duration.
captions[] (optional) Array of caption objects.

URL protocols

Audio Mapping

The audio_map object specifies a channel mapping that allows flexible selection of the input channel and tracks to output. For each output track, an array entry should be specified as <track idx>.<channel idx>. For example, to map a 5.1 audio channel's 2nd and 4th channels as left and right, use [0.2, 0.4]

To use an MXF input and to select track 4 as left and track 7 as right, use [4.0, 7.0].

Note that indexes are 0 based.

Multiple audio-maps can be defined by using an array of arrays as audio_map. For example, for an MXF input with 8 track mono audio, if one of the outputs is stereo and if one of the outputs is 5.1, than you can specify the following for your input audio_map:

audio_map: [      [4.0, 7.0],      [5.0, 6.0, 1.0, 4.0, 3.0] ]

Audio down-mix

Specify "audio_map" : "itu" and the output will be 5.1 to stereo down-mix as specified by the ITU standard.

Adbreaks

Adbreak objects (Job.Input.Adbreaks[]) contain timestamp information about ad breaks in the media. Ad breaks can be defined at a single frame or for a period. If only "begin" parameter is defined, then ad break is at single frame. Ad breaks will be used for ad stitching.

begin Begin timestamp of the ad break.
end (optional) End timestamp of ad break. Specifying an end timestamp implies that the input file has burnt-in ad spots. These are typically used in preserving advertisements in case of C3/D4 scenarios and automatically switching from C3 to D4 when the time comes.

Captions

Caption objects (Job.Input.Captions[]) contain subtitle file information about video files. These files will be embedded in output video file if embedded_caption flag is set true in encoding parameters.

Caption formats

Supported input formats are scc, smpte, srt

Output

A single url that specifies the folder that will hold the files created according to the specified encode_profile_id. See below for supported URL protocols.

URL protocols

Supported upload protocols are same as supported input protocols, with the addition of Aspera

List all Jobs

This endpoint retrieves all jobs.

Try now

Endpoint

GET /latest/job

Query Parameters

Parameter Default Description
page_no 0 0 based page number.
page_sz 20 Number of items in the requested page.
curl "https://encoding.apis.anvato.net/latest/job/"
  -H "Authorization: MCP-TOKEN token=your-access-key"

Create a Job

curl -X POST "https://encoding.apis.anvato.net/latest/job"
  -H "Authorization: MCP-TOKEN token=your-access-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My encode job",
    "input": "http://example.com/input.mp4",
    "encode_profile_id": "235504b8-3c19-47c4-8997-d41cc640507d",
    "output": "ftp://me@p455@example.com/output/my-encode/"
  }'

This endpoint create a Job. The request body should be the JSON encoded job object.

Try now

Endpoint

POST /job/

Cancel a Job

curl -X POST "https://encoding.apis.anvato.net/latest/job/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key" \
  -d state=cancel

This endpoint cancels a Job. You must send state=cancel as the parameter. All other parameters will be ignored.

If the job is already started, the job cannot be cancelled.

Try now

Endpoint

POST /job/<ID>

Get a Specific Job

curl "https://encoding.apis.anvato.net/latest/job/ID"
  -H "Authorization: MCP-TOKEN token=your-access-key"

The above command returns JSON structured like this:

{
  "id": "My encode job id",
  "owner_id": "Owner id",
  "name": "My encode job",
  "spec": {
    "name": "My encode profile",
    "input": "http://example.com/input.mp4",
    "encode_profile_id": "My encode profile id",
    "output": "ftp://me@p455@example.com/output/my-encode/"
  },
  "report": {
    "outputs": [
      {
        "url": "ftp://me@p455@example.com/output/my-encode/2564000.m3u8",
        "resolution": "1280x720",
        "format": "application/x-mpegURL",
        "max_bitrate": 2330224,
        "avg_bitrate": 2330224,
        "codecs": "avc1.64001f, mp4a.40.2"
      },
      {
        "url": "ftp://me@p455@example.com/output/my-encode/output-2564000.json",
        "resolution": "1280x720",
        "format": "application/json",
        "max_bitrate": 2246452,
        "avg_bitrate": 4492904,
        "codecs": "mp4a.40.2, avc1.6401f"
      },
      {
        "url": "ftp://me@p455@example.com/output/my-encode/1264000.m3u8",
        "resolution": "640x360",
        "format": "application/x-mpegURL",
        "max_bitrate": 1213688,
        "avg_bitrate": 1213688,
        "codecs": "avc1.64001e, mp4a.40.2"
      },
      {
        "url": "ftp://me@p455@example.com/output/my-encode/output-1264000.json",
        "resolution": "640x360",
        "format": "application/json",
        "max_bitrate": 1159418,
        "avg_bitrate": 2318836,
        "codecs": "mp4a.40.2, avc1.6401e"
      },
      {
        "url": "ftp://me@p455@example.com/output/my-encode/master.m3u8",
        "format": "application/x-mpegURL",
        "bitrate": "variant"
      }
    ],
    "times": {
      "dl": 0,
      "enc": 1,
      "inp": 5,
      "up": 2
    }
  },
  "state": "complete-success",
  "ts_created": 1481237959,
  "ts_started": 1481237961,
  "ts_ended": 1481237968,
  "progress": 100,
  "analysis": {
    "http://example.com/input.mp4": {
      "tracks": [
        {
          "type": "general",
          "format": "MPEG-4",
          "content_type": "video/mp4",
          "name": "MPEG-4",
          "codec_id": "isom",
          "codec": "MPEG-4",
          "duration": "00:00:05.312 (00:00:05:07)",
          "frame_rate": "25",
          "format_profile": "Base Media",
          "overall_bit_rate": "1589964"
        },
        {
          "type": "video",
          "format": "AVC",
          "content_type": "video/H264",
          "name": "AVC",
          "codec_id": "avc1",
          "codec": "AVC",
          "bitrate": "1205959",
          "duration": "00:00:05.280 (00:00:05:07)",
          "width": "1280",
          "height": "720",
          "frame_rate": "25",
          "format_profile": "Main@L3.1",
          "codec_profile": "Main@L3.1",
          "display_aspect_ratio": "16:9"
        },
        {
          "type": "audio",
          "format": "AAC",
          "name": "AAC",
          "codec_id": "40",
          "codec": "AAC LC",
          "bitrate": "384000",
          "duration": "00:00:05.312 (00:00:05:14)",
          "frame_rate": "46.875",
          "format_profile": "LC",
          "sampling_rate": "48000",
          "channels": "2",
          "channel_positions": "3/2/0.1",
          "channel_layout": "C L R Ls Rs LFE"
        }
      ]
    }
  }
}

This endpoint retrieves a specific Job.

Try now

Endpoint

GET /job/<ID>

Errors

The MCP API uses the following standard error codes:

Error Code Meaning
400 Bad Request -- There was an error with your request, such as missing mandatory field or invalid value.
401 Unauthorized -- Your API key/token is wrong.
403 Forbidden -- Your access level does not allow the requested operation.
404 Not Found -- Object or endpoint does not exist.
405 Method Not Allowed -- Object or endpoint does not support the specified method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- Object was deleted and is no longer available.
429 Too Many Requests -- You must decrease your request rate.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.