API Documentation

Appearance

POST /files/uploads ​

Description ​

Initiates a file upload to the internal store. Returns an upload "session" consisting of the action url to which to make a multipart form-post with the file data to be uploaded as well as a set of form post parameters that must be included as part of the request.

Authentication ​

  • Required: Yes
  • Method: Bearer token

Request Headers ​

  • Authorization: Bearer [AUTH_TOKEN]
  • Accept:
    • application/json (for JSON responses)
    • application/xml (for XML responses)

Query Parameters ​

  • format: string (Optional)
    Values: json, xml
    This will override the Request Accept header.
  • human: boolean (Optional)
    Values: true, false
    Causes the response to be in a structured, more human-readable form. Useful when calling the API through curl or a browser.
  • object_key: string
    Object key which later references the uploaded file (e.g. in Job submissions).
  • pipeline_id: string
    The id of a pipeline. The uploaded object will be created as a object key relative to the respective pipeline's root path.
  • ip: integer (Optional)
    IP address of the uploader as an integer (e.g. obtainable via the ip2long() PHP function). If specified, the form post URL returned to be used with the upload will be geo-optimized to be closer to the given IP's geo-location.
  • expires_at: integer (Optional)
    Epoch timestamp that indicates when to auto-delete the uploaded object from storage again if it hasn't been used with a Job meanwhile. If not set, the default expiry time is 7 days. If you want your uploaded objects to persist indefinitely (even when not used in a Job), set the expires_at parameter to a value of 0 (= never expire).

Example Request ​

bash
curl -X POST -H "Authorization: Bearer AUTH_TOKEN" "https://api.xvid.com/v1/files/uploads/?object_key=uploads%2Ftest.mp4&pipeline_id=53a1ac4914eaa8ffa4fce91b"

Example Response ​

Success (200 OK) ​

json
{
    "upload": {
        "form_post_params": {
            "name": "test.mp4",
            "success_action_status": "201",
            "filename": "",
            "chunk": "0",
            "chunks": "1",
            "policy": "eyJleHBpcmF0aW9uIjoiMjAxNC0wNi0yMFQwOTo0NjowNi4yNzlaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoieHZpZC1tZWRpYWNvZGVyIn0sWyJzdGFydHMtd2l0aCIsIiRuYW1lIiwiIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCI1M2ExYWM0OTE0ZWFhOGZmYTRmY2U5MWIvIl0sWyJzdGFydHMtd2l0aCIsIiRmaWxlbmFtZSIsIiJdLHsiYWNsIjoicHJpdmF0ZSJ9XX0=",
            "signature": "y7eAlMzKsVyNHkKEfN1/DnVTh34=",
            "AWSAccessKeyId": "AKIAINU6WW5PT7GRJLVA",
            "key": "tmp/53a1ac4914eaa8ffa4fce91b/uploads/test.mp4",
            "acl": "private"
        },
        "status": "UPLOADING",
        "object_key": "uploads/test.mp4",
        "nb_chunks": 0,
        "type": "S3",
        "form_post_url": "https://s3-eu-west-1.amazonaws.com/prd-xmc-xvid-s3-eu-west-1/",
        "pipeline": {"id": "53a1ac4914eaa8ffa4fce91b"},
        "file" : {"id": "53a1ac4914eaa8ffa4fce38c"},
        "id": "53a1ac4914eaa8ffa4fce38c"
    }
}

Error Responses ​

400 Bad Request ​

json
{
  "error": {
    "error_code": "0x0230001",
    "error_message": "Invalid Input"
  }
}

403 Forbidden ​

json
{
  "error": {
    "error_code": "0x0000003",
    "error_message": "Invalid access token"
  }
}

404 Not Found ​

json
{
  "error": {
    "error_code": "0x0230002",
    "error_message": "Requested file does not exist"
  }
}

500 Internal Server Error ​

json
{
  "error": {
    "error_code": "0x0000001",
    "error_message": "Internal Error"
  }
}