Documentation

As detailed as we can possibly be. As flexible as ever.

[How EncodeMagic works]


EncodeMagic implements a config-based API which is built with simplicity and flexibility in mind.

A single configuration file is used to describe your entire encoding workflow from transcoding to multiple formats to generating thumbnails of any size and transforming Powerpoint presentations to videos. It is all then submitted to EncodeMagic for processing. So simple.

   

[How EncodeMagic works]


EncodeMagic implements a config-based API which is built with simplicity and flexibility in mind.

A single configuration file is used to describe your entire encoding workflow from transcoding to multiple formats to generating thumbnails of any size and transforming Powerpoint presentations to videos. It is all then submitted to EncodeMagic for processing. So simple.

   

[Jobs]


Creating tasks

To create a conversion task, you just need to make a single HTTP (POST) request to the following URL: 

http://api.encodemagic.com/v1/tasks


Authentication

Tasks need to be authenticated with an API key using Basic Auth. The username is always EM-API-Key and the password should be a valid API key.


HTTP Request

The HTTP request is a regular POST request which uses a json file to describe the task at hand: 

curl -s -v -u EM-API-Key:PRIVATE_KEY -H "Accept: application/json" -H "Content-type: application/json" -X POST --data @mytask.json http://api.rs.encodemagic.com:80/v1/tasks/


HTTP Responses

After a job is successfully submitted, you will receive an HTTP 200 response and the following message: 

{"Task": "803sldjfa-c7e0sd-1ds1e4-a3wf6-421aa90e079f"}

This is the Task ID. Capturing it allows us to poll the system for task status and progress.
Should there be any errors with the task, EncodeMagic will instead return an HTTP 406 response along with a short message describing the problem, whenever possible.
Now, assuming all went well we can send a regular GET request to retrieve the status of a particular task: 

curl -s -v -u EM-API-Key:PRIVATE_KEY http://api.rs.encodemagic.com:80/v1/tasks/803sldjfa-c7e0sd-1ds1e4-a3wf6-421aa90e079f
If the task in question is in progress and has not yet completed then we should receive something among the following lines: 

HTTP 200 OK
Content-Type: application/json
{
    "Status": "Active",
    "ProgressStages": 7,
    "Task": "803sldjfa-c7e0sd-1ds1e4-a3wf6-421aa90e079f",
    "ProgressCurrentStage": 4,
    "ProgressStageTimeLeft": -1,
    "Added": "2015-03-12 12:15:32",
    "TaskType": "VideoToVideo",
    "ProgressStagePercentage": 28,
    "Cause": "Active",
    "Stage": "Converting"
}

Otherwise the response will look similar to this: 

HTTP 200 OK
Content-Type: application/json
{
    "task_uuid": "803sldjfa-c7e0sd-1ds1e4-a3wf6-421aa90e079f",
    "conversion_profile": "VIDEO2MP4",
    "start_date": "2015-03-12T12:15:30Z",
    "end_date": "2015-03-12T12:17:25Z",
    "status": "Completed",
    "sources_size": 7266300,
    "targets_size": 17820771,
    "slide_count": null,
    "page_count": null,
    "word_count": null,
    "video_length": "0",
    "charge": 2.5087071,
    "dl_url": [
        "s3://username:password@my_aws_bucket/my_path/my_file_out.mp4",
        "s3://username:password@my_aws_bucket/my_path/my_file_thumb.jpg",
    ]
}
The task processing has now finished and you should be able to retrieve your data from your Amazon S3 drive.

[Configuration]


Task configuration

EncodeMagic supports a number of configuration options:

Basic Parameters

The following parameters are included in the JSON dictionary as simple key:value pairs.
Keys are always strings containing the parameter name.
Please note that parameter names are case sensitive.

ConversionProfile

Provides the Conversion Profile of the task as a string. Required. Type: string.

Conversions details (like formats, bitrates, filters, etc) are determined through a Conversion Profile. There is a very good selection of predefined Conversion Profiles made available by EncodeMagic. In most cases, these predefined Profiles will fill your needs. This parameter provides the selected Conversion Profile for the specific task.

ApplicationSubmissionID

Provides a string ID used by the Application for reporting reasons. Optional. Type: string.

This ID should be unique for each of the tasks even though EncodeMagic does not perform any cross-checks. This custom ID is used only in logs, reports and billing. It is limited to internal use.

NotifyURL

Provides a URL that will be called when the Task has finished processing. Required. Type: string.

Set by the user, this field is required so that when a task is finished, EncodeMagic performs a GET request to that URL to notify about the end of the encoding operation. Please note that this does not always imply a successful conversion operation.

Priority

Affects Pricing. Provides the Priority that this Task will run under. Optional. Type: string.

Currently under construction. Different Priorities are priced differently, allowing for Applications to have the optimum balance between cost and performance. By default, all Tasks are run in the default Normal priority.
Valid string values are:

Sources

Provides the input media for the Task. Required. Type: list (of dictionaries).

Sources are the input media files which are used for the Task. Each Source usually represents a single file but you may choose to include more than one if for instance you need to include a watermark along with your video. Sources are collected before initiating encoding. The Sources element is a JSON List, containing JSON mappings/dictionaries each representing a single Source. They can take the following options:

Targets

Specifies the target media for the Task. Required. Type: list (of dictionaries).

Targets are the resulting media files that are produced by EncodeMagic. Each Target represents a single file.
Targets are stored after the encoding process has completed.

The Targets element is a JSON List, containing JSON mappings/dictionaries each representing a Target. Documentation for each of the parameneters follows:

[Task Status]


The system can provide status updates and other information in accordance to the submitted task. All requests need to be authenticated.

Requests

Requests use the HTTP GET method at: 

http://api.rs.encodemagic.com:80/v1/tasks/TaskID
where TaskID is the ID of the task returned after the task submission earlier.

Responses

While a task is in Active state, (which means it is currently being processed by the system and has't yet completed nor failed either) EncodeMagic can provide some useful information about its state:

{
    'Task': '5227291e-d89a-11e1-8b1c-3202dddf66e1',
    'Added': '2012-06-25T13:45:01',
    'Status': 'Active',
    'Cause': 'Active',
    'Stage': 'WaitingSource',
    'ProgressStages': 6,
    'ProgressCurrentStage': 1,
    'ProgressStagePercentage': 12,
    'ProgressStageTimeLeft': 26524,
    'ProgressPercentage': 0.056,
    'ProgressTimeLeft': 77543,
}

[Task End State]


Responses

After a task has finished processing, which means that is no longer in Active state, the HTTP RESPONSE upon a task STATUS REQUEST at: 

http://api.rs.encodemagic.com:80/v1/tasks/TaskID
slightly changes to this: 

{
    "task_uuid": "de0192c2-cd5d-11e4-bd47-421aa90e079f",
    "conversion_profile": "VIDEO2MP4",
    "start_date": "2015-03-20T10:59:36Z",
    "end_date": "2015-03-20T11:02:54Z",
    "status": "Completed",
    "sources_size": 31230560,
    "targets_size": 12992503,
    "slide_count": null,
    "page_count": null,
    "word_count": null,
    "video_length": "0",
    "charge": 4.4223063,
    "dl_url": [
        "http://mybucket.s3.amazonaws.com/file_out.mp4"
    ]
}

Let's break down what all those new attributes are:

Not conviced yet?

Unfortunately new registrations are now closed.