File Uploads¶

Two-step process¶

Every time an API call has the option to upload a file, it can be done using a two-step process:

• First, the API create or update call is done. The call will return an upload URL.
• Second, the file is submitted to this upload URL using multipart/form-data HTTP POST method.

This two-step process allows us to directly deliver files at our transcoding server. It allows API users to directly upload from the client’s computer instead of going through the web server that executes the calls.

Upload URL¶

After executing an API call that has an upload option, its response will include a link block with parameters that can be used to construct the upload URL. For example, here is the response of a /videos/create API call:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <video key="tL17msiU">
    <link>
      <protocol>http</protocol>
      <address>upload.bitsontherun.com</address>
      <path>/v1/videos/upload</path>
      <query>
        <key>vtQmcboj</key>
        <token>e2bbad0fd889d5d2e30047596cfe3789778257d2</token>
      </query>
    </link>
  </video>
</response>

The upload URL should be concatenated from the parts of the link block using the following scheme:

upload_url = <link/protocol> + "://" + <link/address> + <link/path> +
    "?api_format=<one of: py, json, xml, php>" +
    "&key=" + <link/query/key> +
    "&redirect_address=" + <redirect_address> +
    "&redirect_query.<param_name1>=" + <param_value1> +
    "&redirect_query.<param_name2>=" + <param_value2> +
    "&key_in_path=" + <key_in_path> +
    "&token=" + <link/query/token>

That should produce the following upload URL using response example from above:

http://upload.bitsontherun.com/v1/videos/upload
    ?api_format=xml
    &key=vtQmcboj
    &token=e2bbad0fd889d5d2e30047596cfe3789778257d2

Redirect parameters¶

In addition to the parameters in the link block, the following redirect query parameters can be added to the upload URL:

redirect_address (optional) : string

Redirect address string using the following format:

<protocol>://<host>/<path>

redirect_query.param (optional) : string

Redirect query parameter. param part of the redirect parameters (after the ‘.’ separator) specifies name of the parameter. Redirect query parameter can be specified multiple times, as far as parameter name is unique.

key_in_path (optional) : string

Specifies if //video/@key should be added as a query parameter to the redirect URL, or at the end of the URL path.

True

Add value of the //video/@key at the end of the URL path:

http://<host>/<path>/<key>

False

Add value of the //video/@key as video_key query parameter:

http://<host>/<path>?video_key=<key>

Default is False.

When using these redirect parameters, the upload URL should look like this:

http://upload.bitsontherun.com/v1/videos/upload
    ?api_format=xml
    &key=vtQmcboj
    &redirect_address=http://example.com/path
    &redirect_query.parameter1=value1
    &redirect_query.parameter2=value2
    &key_in_path=True
    &token=e2bbad0fd889d5d2e30047596cfe3789778257d2

Using the upload URL¶

After upload URL has been constructed, it can be used as an action parameter in an HTML form:

<form method="POST"
     action="http://upload.bitsontherun.com/v1/videos/upload
     ?api_format=xml&key=vtQmcboj
     &token=e2bbad0fd889d5d2e30047596cfe3789778257d2"
     enctype="multipart/form-data">
  <fieldset>
  <input type="file" name="file" />
  <button type="submit">Upload</button>
  </fieldset>
</form>

It can also be used as a URL parameter, e.g. when using cURL:

curl --form file=@./video.mpeg
    "http://upload.bitsontherun.com/v1/videos/upload
     ?api_format=xml
     &key=vtQmcboj
     &token=e2bbad0fd889d5d2e30047596cfe3789778257d2"

Example response¶

This is an example response of a successful video file upload.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <video key="tL17msiU">
    <md5>6d4063f37eed1e847ed17b7be6364546</md5>
    <size>21545452</size>
  </video>
  <redirect_link>
    <address>http://example.com/path/tL17msiU</address>
    <query>
      <parameter1>value1</parameter1>
      <parameter2>value2</parameter2>
    </query>
  </redirect_link>
</response>

Response parameters¶

/response/status : string

Upload status. Set to ok if upload was successfully.

//video/@key : string

Video key.

//video/md5 : string

Video file MD5 message digest calculated by the upload server after the file was successfully received.

//video/size : unsigned integer

Size of the received video file in bytes.

//video/redirect_link/address : string

Redirect address.

//video/redirect_link/query/parameter : string

Redirect URL query parameter.

Tracking file upload progress¶

File upload progress can be tracked by polling upload progress URL. This URL should be constructed by concatenating parts of the link block returned by create or update API call and specifying JSON-P callback function name using the following scheme:

upload_progress_url = <link/protocol> + "://" + <link/address> +
    "/progress?token=" + <link/query/token> + "&callback=callback"

That should produce the following progress request URL using response example from above:

http://upload.bitsontherun.com/progress
    ?token=e2bbad0fd889d5d2e30047596cfe3789778257d2
    &callback=callback

Upload progress tracking responses¶

Upload progress URL returns upload status in JSON-P format. The following responses are possible:

Upload for specified token not yet started or token is invalid

callback(
  {
    'state' : 'starting'
  }
);

Upload is in progress

callback(
  {
    'state' : 'uploading',
    'received' : <received bytes>,
    'size' : <file size in bytes>
  }
);

Upload is finished

callback(
  {
    'state' : 'done'
  }
);

An error has occurred during file upload

callback(
  {
    'state' : 'error',
    'status' : <HTTP status number>
  }
);