Upload files

📘

TIP

For video file uploads of up to 5GB, we strongly recommend using the s3 upload method over standard file uploads. In practice, the CDN accelerated s3 uploads are the fastest and most reliable means to get a file from a local system to JW Platform.

The uploading of files (videos, images and skins) is an integral part of the JW Platform Management API. There’s various API calls that have an upload option. The upload process is exactly the same for each of these calls. While a file is uploading, progress information can be given to the user.

Please note, examples given below are for uploading a video file using /videos/create API call. If you uploading using other API calls, please change:

videos part of the upload URL to:

• accounts/skins for method_accounts_skins_create API call
• accounts/skins for method_accounts_skins_update API call
• accounts/images for method_accounts_images_create API call
• accounts/images for method_accounts_images_update API call
• videos/thumbnails for /videos/thumbnails/update API call
• videos/tracks for /videos/tracks/create API call

parameter names video and video_key to:

• skin and skin_key for method_accounts_skins_create API call
• skin and skin_key for method_accounts_skins_update API call
• image and image_key for method_accounts_images_create API call
• image and image_key for method_accounts_images_update API call
• video and video_key for /videos/thumbnails/update API call
• track and track_key for /videos/tracks/create API call

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:

{
  "status": "ok",
  "media": {
    "type": "video",
    "key": "tL17msiU"
  },
  "link": {
    "path": "/v1/videos/upload",
    "query": {
      "key": "vtQmcboj",
      "token": "e2bbad0fd889d5d2e30047596cfe3789778257d2"
    },
    "protocol": "http",
    "address": "upload.jwplatform.com"
  },
  "rate_limit": {
    "reset": 1572450240,
    "limit": 60,
    "remaining": 59
  },
  "session_id": "kwJei9j2vtQmcbojrlGJY3mbJFMHfzZwPXBwoSQr"
}

📘

Note

Although the API response returns "link.protocol": "http", you can use either the HTTP or HTTPS protocol for the upload URL.

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.jwplatform.com/v1/videos/upload?api_format=xml&key=vtQmcboj&token=e2bbad0fd889d5d2e30047596cfe3789778257d2

Please note, upload token will expire after 7 days. After that new asset should be created using corresponding API create call, or for the existing assets with ready state, an API update call should be used.

Redirect parameters

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

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

http://upload.jwplatform.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

👍

IMPORTANT

Any uploaded file must have a minimum duration of 2 seconds.

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

<form method="POST" action="http://upload.jwplatform.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 [email protected]/video.mpeg
    "http://upload.jwplatform.com/v1/videos/upload?api_format=xml&key=vtQmcboj&token=e2bbad0fd889d5d2e30047596cfe3789778257d2"

❗️

WARNING

Form input field name for the file path must be set to file. Any other field name will not be picked up by the upload server.

Example response

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

{
  "status": "ok",
  "video": {
    "key": "tL17msiU",
    "md5": "6d4063f37eed1e847ed17b7be6364546",
    "size": "21545452"
  },
  "redirect_link": {
    "address": "http://example.com/path/tL17msiU",
    "query": {
      "parameter1": "value1",
      "parameter2": "value2"
    }
  }
}

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.jwplatform.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.

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

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

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

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