Uploads Resource


The Uploads resource is a sub-resource to the Files resource. It deals with uploading actual, binary file content to the internal storage space. 

Uploading a new file is a three-step procedure:

1) Initiating a new Upload session
2) Uploading the actual file data by performing a multipart form-post to the upload URL with form post parameters returned as result of Step 1
3) Finish the File Upload 

Complete example using the "curl" command:


Step 1): Obtaining a new Upload session

POST /files/uploads
curl -X POST -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" "https://api.xvid.com/v1/files/uploads/?object_key=uploads%2Ftest.mp4&pipeline_id=547f3eede4b025bcbff38657"

{
  "upload":
  {
    "form_post_params":
    {
      "name":"test.mp4",
      "success_action_status":"201",
      "filename":"",
      "chunk":"0",
      "chunks":"1",
      "policy":"eyJleHBpcmF0aW9uIjoiMjAxNy0wOC0wM1QxNzo0MDoyMi4wMzlaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoicHJkLXhtYy14dmlkLXMzLWV1LXdlc3QtMSJ9LFsic3RhcnRzLXdpdGgiLCIkbmFtZSIsIiJdLFsic3RhcnRzLXdpdGgiLCIka2V5IiwidG1wLzU0N2YzZWVkZTRiMDI1YmNiZmYzODY1Ny8iXSxbInN0YXJ0cy13aXRoIiwiJGZpbGVuYW1lIiwiIl0sWyJzdGFydHMtd2l0aCIsIiRjaHVuayIsIiJdLFsic3RhcnRzLXdpdGgiLCIkY2h1bmtzIiwiIl0seyJhY2wiOiJwcml2YXRlIn0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDEifV19",
      "signature":"uEs+mYfUHrD3+XlCILU/i4ZLJUs=",
      "AWSAccessKeyId":"AKIAJOQBR4U6ZJTE27LQ",
      "key":"tmp/547f3eede4b025bcbff38657/uploads/test.mp4",
      "acl":"private"
    },
    "form_post_url":"https://s3-eu-west-1.amazonaws.com/prd-xmc-xvid-s3-eu-west-1/",
    "status":"UPLOADING",
    "nb_chunks":0,
    "storage_type":"S3",
    "object_key":"uploads/test.mp4",
    "pipeline":{"id":"547f3eede4b025bcbff38657"},
    "file":{"id":"598358fe6baa605b1e33754e"},
    "id":"598358fe6baa605b1e33754e"
  }
}


Step 2): Posting the actual file data in a multipart form-post to the "form_post_url" with all the "form_post_params" parameters returned by Step 1. The actual file binary data is sent as "file" parameter. This step can be safely performed client side, e.g. via javascript in a browser.

Multipart form-post
curl -F "name=test.mp4" -F "success_action_status=201" -F "filename=" -F "chunk=0" -F "chunks=1" -F "policy=eyJleHBpcmF0aW9uIjoiMjAxNy0wOC0wM1QxNzo0MDoyMi4wMzlaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoicHJkLXhtYy14dmlkLXMzLWV1LXdlc3QtMSJ9LFsic3RhcnRzLXdpdGgiLCIkbmFtZSIsIiJdLFsic3RhcnRzLXdpdGgiLCIka2V5IiwidG1wLzU0N2YzZWVkZTRiMDI1YmNiZmYzODY1Ny8iXSxbInN0YXJ0cy13aXRoIiwiJGZpbGVuYW1lIiwiIl0sWyJzdGFydHMtd2l0aCIsIiRjaHVuayIsIiJdLFsic3RhcnRzLXdpdGgiLCIkY2h1bmtzIiwiIl0seyJhY2wiOiJwcml2YXRlIn0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDEifV19" -F "signature=uEs+mYfUHrD3+XlCILU/i4ZLJUs=" -F "AWSAccessKeyId=AKIAJOQBR4U6ZJTE27LQ" -F "key=tmp/547f3eede4b025bcbff38657/uploads/test.mp4" -F "acl=private" -F "file=@./test.mp4" https://s3-eu-west-1.amazonaws.com/prd-xmc-xvid-s3-eu-west-1/

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse><Location>https://s3-eu-west-1.amazonaws.com/prd-xmc-xvid-s3-eu-west-1/tmp%2F547f3eede4b025bcbff38657%2Fuploads%2Ftest.mp4</Location><Bucket>prd-xmc-xvid-s3-eu-west-1</Bucket><Key>tmp/547f3eede4b025bcbff38657/uploads/test.mp4</Key></PostResponse>


Note: If the file data is uploaded in more than one chunk, each chunk must be uploaded with a unique object "key" parameter containing the chunk number as a suffix (e.g. "test.mp4.0", "test.mp4.1", "test.mp4.2", etc.) and the chunk numbering must start with "0" for the first chunk, then incremented with each chunk and sent as the "chunk" form parameter. 


Step 3): Finalizing the upload by updating the upload session with the number of actually uploaded chunks. The upload id to provide as reference is the id that was returned in Step 1.


Note: Finalizing the upload and combining the various chunks (in case the file was uploaded in multiple chunks) is an asynchronous task and may take a few seconds depending on the size of the uploaded file data. You can check the status by performing a GET /files/uploads/ID - when the "status" field in the returned JSON object has turned from "COMPLETING" to "SUCCESS", the finalizing step has completed and the uploaded file is now ready (e.g. for use in a subsequent /jobs API POST). 

 

PUT /files/uploads/ID
curl -X PUT -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" -d '{"upload": {"nb_chunks": 1}}' "https://api.xvid.com/v1/files/uploads/598358fe6baa605b1e33754e"

{
  "upload":
  {
    "form_post_url": "https://s3-eu-west-1.amazonaws.com/prd-xmc-xvid-s3-eu-west-1/",
    "status": "COMPLETING",
    "nb_chunks": 1,
    "storage_type": "S3",
    "object_key": "uploads/test.mp4",
    "pipeline": {"id":"547f3eede4b025bcbff38657"},
    "file":{"id":"598358fe6baa605b1e33754e"},
    "id":"598358fe6baa605b1e33754e"
  }
}


The Uploads resource supports the following methods:

Available Methods

  • No labels