If you are interested in integrating your own hardware, software or service to our cloud-based service we provide an easy-to-use REST API for this purpose. The sample code below uses PHP but should be fairly easy to port to other languages. For security reasons never call this API from web client code such as Javascript.

The current version of the API is 1.0.

Overview

All requests should be sent using the POST method over HTTPS. We don't support unencrypted HTTP transfers. Requests and responses are sent as JSON-formatted strings. All requests are case insensitive and all responses should also be considered to be case insensitive.

The base URL for accessing the API is https://www.recuromedia.com/api/X.Y where X.Y is the version being used. Version 1.0 or 1.0.4 would both use the following URL. 

https://www.recuromedia.com/api/1.0/

Authentication

All requests should contain an Authorization header with your API key and secret in "ApiKey:ApiSecret" format. Here is an example header. 

Authorization: K34Zz6AqrQPuhTBj:RkeD3wrU7vAMzX9JFghQZGaBYSfc2pbT


In your account under the menu "My Account -> Administrator Tools" you can create your own API keys that you should use to authenticate yourself to the API. The API is currently rate limited to a maximum of 200 requests/minute.

HTTP Status Codes

A response from the API will contain one of the HTTP status codes listed below. Any other HTTP status code will come from the web server and not the API. 

200   OK
400   Client Error
500   Server Error

Error Responses

If a request failed (any HTTP status code but 200 is returned) and the request is sent from the API and not the web server, the body of the response will always contain a JSON-formatted string with an error_code and error_message. Here is an example response. 

{
  "error_code": "FileIdMissing",
  "error_message": "You need to specify a 'file_id' in your request."
}

Downloading File

Once you get the download URL to your restored media it can be downloaded using the same authentication mechanism as the API uses. Here is an example using cURL. 

curl --retry 60 --retry-delay 30 --retry-connrefused -L -J -O -C - -H "Authorization:K34Zz6AqrQPuhTBj:RkeD3wrU7vAMzX9JFghQZGaBYSfc2pbT"
"https://www.recuromedia.com/download.php?guid=1c8d4737-a0d4-42fb-8276-271426eb9128"

Request Listing

Here is a summary of all possible requests for this version of the API. 

UploadMedia
Upload the specified media to the site and start analyzing it.

StartJob
Start a job restore process for the specified media using the supplied settings.

DeleteMedia
Delete specified media and all associated files.

ListMedia
Retrieve all media thas has already been uploaded.

ListFilters
Retrieve all available filters along with a description and example HTML5 video link for each filter.

ListOutputFormats
Retrieve all available output formats along with a long name for each output format.

GetProgress
Get the progress of the restoration process for specified media.

Example Restoration

Here is an example flow of a restoration from start to finish. 

1) UploadMedia
Call this request to tell the server to download a supplied link to your media. Use the callback to get a notification once a media is ready for restoration.

2) StartJob
Start restoring the specified media using the supplied settings. Use the callback to get a notification of when a media has been restored.

3) Download
Use a call similar to the cURL call seen above to download the restored media.

4) Delete
Delete specified media and all associated files.

The other requests can be seen as helper requests. They are not necessary to implement but might make your implementation more complete and future proof.

Requests

ListMedia

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "ListMedia".

PROPERTY               TYPE               DESCRIPTION

  file_id                string             Unique identifier for a specific media.
  restored_file_url      string             An URL to the restored media if it exists.


  The response is returned as an array of the above.

REQUEST

  {
    "action": "ListMedia"
  }


RESPONSE

  [
    {
      "file_id": "ids-345643.mov",
      "restored_file_url": "https://www.recuromedia.com/download.php?guid=1c8d4737-a0d4-42fb-8276-271426eb9128"
    },
    {
      "file_id": "ids-542452.mov",
      "restored_file_url": ""
    }
  ]
// Setup request JSON object
$request['action'] = 'ListMedia';
$request_json = json_encode($request);

// Setup 'ListMedia' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem'    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

ListFilters

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "ListFilters".

PROPERTY               TYPE               DESCRIPTION

  name                   string             The name of the filter used in the "StartJob" request.
  description            string             A text describing the functionality of the filter.
  example_url            string             An URL to an HTML5 video link that shows what the filter does.


  The response is returned as an array of the above.

REQUEST

  {
    "action": "ListFilters"
  }


RESPONSE

  [
    {
      "name": "MediumDustAndScratches",
      "description": "Removes stray hairs, retouch scratches and repairs damaged frames.",
      "example_url": "https://www.recuromedia.com/movies/Dust%20and%20Noise.mp4"
    },
    {
      "name": "ColorBalance",
      "description": "Evens the white balance and removes discolourations often found in aged film.",
      "example_url": "https://www.recuromedia.com/movies/Color%20and%20Contrast.mp4"
    }
  ]
// Setup request JSON object
$request['action'] = 'ListFilters';
$request_json = json_encode($request);

// Setup 'ListFilters' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem'    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

ListOutputFormats

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "ListOutputFormats".

PROPERTY               TYPE               DESCRIPTION

  name                   string             The name of the output format used in the "StartJob" request.
  long_name              string             A long name description of container and video codec in output format.


  The response is returned as an array of the above.

REQUEST

  {
    "action": "ListOutputFormats"
  }


RESPONSE

  [
    {
      "name": "MovProRes422Hq",
      "long_name": "MOV (ProRes 422 HQ)"
    },
    {
      "name": "Mp4H264",
      "long_name": "MP4 (H.264)"
    }
  ]
// Setup request JSON object
$request['action'] = 'ListOutputFormats';
$request_json = json_encode($request);

// Setup 'ListOutputFormats' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem'    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

UploadMedia

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "UploadMedia".
  original_file_url      string             URL to where the original media file can be located. Supported formats are MKV, MOV, MP3, MP4, MPG, MXF and WAV.
  username               string             [optional] A username to use when accessing the media.
  password               string             [optional] A password to use when accessing the media.
  notify_url             string             [optional] An URL that will be called using POST once the upload and analyzing of media has completed.


  -notify_url
     If the request was successful the request body will contain a JSON string similar to the following example:

     {
       "file_id": "ids-345643.mov",
       "error_code": "MediaCompleted",
       "error_message": "Media completed successfully."
     }

     If the request failed the request body will contain a JSON string equal to:

     {
       "file_id": [file_id],
       "error_code": [error code],
       "error_message": [error message]
     }

PROPERTY               TYPE               DESCRIPTION

  file_id                string             Unique identifier for this media to be used with "GetProgress" and "StartJob" requests.

REQUEST

{
  "action": "UploadMedia",
  "original_file_url": "https://www.mysite.com/5fJwe346gjRs3JtDe64UJ6fjK3KfhJK4/media.mov",
  "notify_url": "https://www.mysite.com/uploadcompleted.php"
}


RESPONSE

{
  "file_id": "ids-345643.mov"
}
// Setup request JSON object
$request['action'] = 'UploadMedia';
$request['original_file_url'] = 'https://www.mysite.com/5fJwe346gjRs3JtDe64UJ6fjK3KfhJK4/media.mov';
$request['notify_url'] = 'https://www.mysite.com/uploadcompleted.php';
$request_json = json_encode($request);

// Setup 'UploadMedia' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem',    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// "notify_url" can access the request body using the code below.
if ($_SERVER["REQUEST_METHOD"] == "POST") {
  // Get raw input and decode json string
  $body_json = file_get_contents("php://input");
  $body = json_decode($body_json, true);
}

StartJob

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "StartJob".
  file_id                string             Unique identifier for this media as received from "UploadMedia".
  output_format          string             Requested output format. Use "ListOutputFormats" to get available formats.
  filters                array              An array of strings with filters to apply. Use "ListFilters" to get available filters.
  output_scaling         string             [optional] The desired output resolution for media. Supported values are '1080' (for HD) and '2160' (for 4K).
  notify_url             string             [optional] An URL that will be called using POST once the restoration job has completed.


  -output_format
     Currently available are "MxfDnxHrHqx", "MxfDnxHr444", "MovProRes422Hq", "MovProRes4444", "Mp4H264", "Mp4Hevc".

  -filters
     Currently available are "LightDustAndScratches", "MediumDustAndScratches", "HeavyDustAndScratches", "Noise", "ReGrain", "ColorBalance", "ColorSaturation",
     "ContrastExpansion", "Colorize", "ImageStabilization", "ReduceFlicker", "ContentStabilization", "VerticalScratches", "RepairDeinterlace", "HighFrameRate",
     "BadSceneChanges", "ColorCasting", "AdaptiveSharpness", NaturalSpeed", "NormalizeVolume", "ReduceNoise", "IncreaseClarity".

  -notify_url
     If the request was successful the request body will contain a JSON string similar to the following example:

     {
       "file_id": "ids-345643.mov",
       "error_code": "JobCompleted",
       "error_message": "Job completed successfully.",
       "restored_file_url": "https://www.recuromedia.com/download.php?guid=1c8d4737-a0d4-42fb-8276-271426eb9128"
     }

     If the request failed the request body will contain a JSON string equal to:

     {
       "file_id": [file_id],
       "error_code": [error code],
       "error_message": [error message]
     }

PROPERTY               TYPE               DESCRIPTION

  HTTP status code 200 is returned if successful, body is empty.

REQUEST

  {
    "action": "StartJob",
    "file_id": "ids-345643.mov",
    "output_format": "MovProRes422Hq",
    "notify_url": "https://www.mysite.com/jobcompleted.php",
    "filters": [
      "MediumDustAndScratches",
      "Noise",
      "ImageStabilization"
    ]
  }


RESPONSE

  HTTP status code 200 is returned if successful, body is empty.
// Setup request JSON object
$request['action'] = 'StartJob';
$request['file_id'] = 'ids-345643.mov';
$request['output_format'] = 'MovProRes422Hq';
$request['notify_url'] = 'https://www.mysite.com/jobcompleted.php';
$request['filters'] = array('ColorBalance', 'ColorSaturation', 'ContrastExpansion', 'ImageStabilization');
$request_json = json_encode($request);

// Setup 'StartJob' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem',    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource (response body is empty)
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// "notify_url" can access the request body using the code below.
if ($_SERVER["REQUEST_METHOD"] == "POST") {
  // Get raw input and decode json string
  $body_json = file_get_contents("php://input");
  $body = json_decode($body_json, true);
}

GetProgress

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "GetProgress".
  file_id                string             Unique identifier for this media as received from "UploadMedia".

PROPERTY               TYPE               DESCRIPTION

  state                  string             Describes the current state of the progress.
  progress               float              A number between 0 and 100 describing the progress for each state.
  restored_file_url      string             An URL to the restored media.


  -state
     Will be one of "MediaUploading", "MediaQueued", "MediaInformation", "MediaScenes", "MediaAnalyze", "MediaCompleted", "JobQueued", "JobQueuedColorization", "JobPreProcessing", "JobColorizing", "JobPostProcessing", "JobRunning", "JobUploading", "JobCompleted".
     These states will appear in ascending order as progress is made.

  -restored_file_url
     Will only be present once state has reached "JobCompleted".

REQUEST

{
  "action": "GetProgress",
  "file_id": "ids-345643.mov"
}


RESPONSE

{
  "state": "JobCompleted",
  "progress": "100",
  "restored_file_url": "https://www.recuromedia.com/download.php?guid=1c8d4737-a0d4-42fb-8276-271426eb9128"
}
// Setup request JSON object
$request['action'] = 'GetProgress';
$request['file_id'] = 'ids-345643.mov';
$request_json = json_encode($request);

// Setup 'GetProgress' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem'    // This is only needed if HTTPS requests aren't working with your client
);

// Get response JSON object, http status code and close curl resource
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

DeleteMedia

PROPERTY               TYPE               DESCRIPTION

  action                 string             Should be "DeleteMedia".
  file_id                string             Unique identifier for this media as received from "UploadMedia".

PROPERTY               TYPE               DESCRIPTION

  HTTP status code 200 is returned if successful, body is empty.
REQUEST

{
  "action": "DeleteMedia",
  "file_id": "ids-345643.mov"
}


RESPONSE

  HTTP status code 200 is returned if successful, body is empty.
// Setup request JSON object
$request['action'] = 'DeleteMedia';
$request['file_id'] = 'ids-345643.mov';
$request_json = json_encode($request);

// Setup 'DeleteMedia' request (cacert.pem available at https://curl.haxx.se/docs/caextract.html)
$ch = curl_init();
curl_setopt_array($ch, array(
  CURLOPT_HTTPHEADER => array("Authorization: $api_key:$api_secret", "Content-Type: application/json"),
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => 'https://www.recuromedia.com/api/1.0/',
  CURLOPT_POST => 1,
  CURLOPT_POSTFIELDS => $request_json,
  CURLOPT_CAINFO => 'path/to/cacert.pem'    // This is only needed if HTTPS requests aren't working with your client
));

// Get response JSON object, http status code and close curl resource (response body is empty)
$response_json = curl_exec($ch);
$http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);