Upload files
You can now use the Platform Management API v2 to upload your content.
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.
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.
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 callaccounts/skins
for method_accounts_skins_update API callaccounts/images
for method_accounts_images_create API callaccounts/images
for method_accounts_images_update API callvideos/thumbnails
for/videos/thumbnails/update
API callvideos/tracks
for/videos/tracks/create
API call
parameter names video
and video_key
to:
skin
andskin_key
for method_accounts_skins_create API callskin
andskin_key
for method_accounts_skins_update API callimage
andimage_key
for method_accounts_images_create API callimage
andimage_key
for method_accounts_images_update API callvideo
andvideo_key
for/videos/thumbnails/update
API calltrack
andtrack_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
HTTPPOST
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:
Parameter | Description |
---|---|
key_in_path 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 . |
redirect_address string | Redirect address string using the following format: <protocol>://<host>/<path> |
redirect_query.param 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. |
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"
}
}
}
Parameters | Description |
---|---|
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 number (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.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>
}
);
Updated 10 months ago