Upload with a resumable protocol


📘

You can now use the Platform Management API v2 to upload your content.


Large video files can be uploaded using a resumable file upload protocol. This method allows to continue file upload only for the remaining part of the file after a network interruption.


📘

TIP

We strongly recommend using the s3 upload method over resumable 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 (even for unreliable or low bandwidth connections).


Upload media

Use the following steps to upload your media:

  1. Make a POST /v1/videos/create (to create a new media object) or POST /v1/videos/update (to update an existing media object). Within the JSON body, set upload_method to multipart and define the metadata of the media item. In the following sample, only the media item's title is defined.
curl -X POST https://api.jwplayer.com/v1/videos/create?api_nonce={API_NONCE}&api_timestamp={API_TIMESTAMP}&api_signature={API_SIGNATURE}&api_key={SITE_ID} \
 -H 'Content-Type: application/json' \
 -d '{ "upload_method": "multipart", "title": "My Uploaded Video" }'

The API call returns a response that includes a link object.

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

  1. Use the properties of the link object to create the upload_url.
upload_url = link.protocol + "://" + link.address + link.path +
    "?api_format={one of: py, json, xml, php}" +
    "&key=" + link.query.key

The above concatenation should produce an upload URL structure similar to the following example.

http://upload.jwplatform.com/v1/videos/upload/resumable?api_format=xml&key=vtQmcboj

📘

TIP

In addition to the parameters in the link block, you can optionally add the following redirect query parameters to the upload URL:


key_in_path boolean: Specifies if media.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 media.key at the end of the URL path: http://{HOST}/{PATH/{MEDIA.KEY}
  • False: Add value of the media.key as video_key query parameter: http://{HOST}/{PATH}?video_key={MEDIA.KEY}

Default is False.


redirect_address string: Redirect address string using the following format: {PROTOCOL}://{HOST}/{PATH}


redirect_query.param string: Redirect query parameter.

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


The following is an example upload URL that uses these redirect parameters:

http:// upload.jwplatform.com/v1/videos/upload/resumable
   ?api_format=json
   &key=vtQmcboj
   &redirect_address=http:// example.com/path
   &redirect_query.parameter1=value1
   &redirect_query.parameter2=value2
   &key_in_path=True


  1. Determine the byte range of each media chunk.

  1. Upload each chunk to the upload URL. The request headers shown in the following example are required. The body of the request must contain a chunk of the file that corresponds to the range specified in the X-Content-Range header.
POST /v1/videos/upload/resumable?api_format=xml&key=vtQmcboj&redirect_address=http://example.com/path&redirect_query.parameter1=value1&redirect_query.parameter2=value2&key_in_path=True 
HTTP/1.1
Host: upload.jwplatform.com
Content-Length: 1234567
Content-Disposition: attachment; filename="video.mpeg"
Content-Type: application/octet-stream
X-Content-Range: bytes 0-1234566/96768273
X-Session-ID: kwJei9j2vtQmcbojrlGJY3mbJFMHfzZwPXBwoSQr

<bytes 0-1234566>
HeaderDescription
Content-Dispositionattachment; filename="{YOUR_FILE_NAME}"
Content-TypeMIME type of a file being uploaded

MIME type must not be set to multipart/form-data. If MIME type of the file cannot be determined, application/octet-stream may be used.
X-Content-RangeByte range of the chunk being uploaded and total size of the file in bytes using bytes <chunk_start_byte>-<chunk_end_byte>/<file_size> format

IMPORTANT: The first byte of a file is 0. This means that the last byte is n-1, where n is the total size of the file in bytes. Use this information when defining byte ranges.
X-Session-IDResumable upload session ID

The session_id is returned in the POST /videos/create or POST /videos/update API call.

After the upload server acknowledges a successful chunk upload with a 201 Created HTTP status response, the next file chunk may be uploaded.

HTTP/1.1 201 Created
Date: Wed, 08 Aug 2012 09:24:34 GMT
Content-Length: 18
Range: 0-1234566/96768273

0-1234566/96768273

👍

IMPORTANT

If the file upload is interrupted due to a network connection issue or a user-initiated pause, the client should resume the process by uploading the file chunk from the 0 byte position.

The upload server will respond with the combined byte range received in the previous upload session(s). If the uploaded chunk was previously received, it will be discarded.

The client must use the received byte range to determine the start byte for the next file chunk. For example, if the upload server responds with the received byte range 0-52370332/96768273, the next file chunk start byte must be 52370333.



After all parts have been uploaded, the API returns information about the uploaded video. The following example includes redirect parameters.

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

Did this page help you?