API Documentation

Appearance

GET /files/downloads ​

Description ​

Download file from internal store. This endpoint allows querying absolute, downloadable URLs of files created by a successfully finished conversion job or uploaded earlier via a call to /files/uploads.

Authentication ​

  • Required: Yes
  • Method: Bearer token or HMAC

Request Headers ​

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

Parameters ​

Query Parameters ​

  • format: string (Optional)
    Values: json, xml
    Overrides the Request Accept header.
  • human: boolean (Optional)
    Values: true, false
    Causes the response to be in a structured, more human-readable form.
  • object_key: string (Optional)
    Object key (relative path) of the file on the store. For example, for job outputs the object key is composed of the job's output_prefix + the output_name of the job output (plus the proper file extension).
  • pipeline_id: string (Optional)
    The ID of the pipeline relative to which the given object key applies.
  • file_id: string (Optional)
    ID specifying a file/archive in the Files resource. If the specified ID refers to an archive, a list of URLs — one for each of the archive's items — is returned instead of a single URL.
  • autograph_tag: string (Optional)
    A unique tag to be embedded dynamically with the download for traceability via Xvid AutoGraph watermarking technology. Only set this parameter for files that have the "autograph": true property — do not set it otherwise!
  • redirect: boolean (Optional)
    Values: true, false (default: false)
    If set to true, responds with a HTTP 302 redirect instead of the URL coded as JSON.
  • expiry_time: int (Optional)
    Desired expiry time (as seconds since epoch) to attach to the returned/redirected download link. Note: Epoch timestamps are UTC by definition — make sure to compute the value from the current UTC time, not your webserver's local time.
  • anti_fraud: boolean (Optional)
    Enable a set of features to prevent link sharing, block users behind anonymizing proxies, and block black-listed IPs of well-known pirates from downloading the file. Use with care, as legitimate users can be affected by these checks too!
  • max_parallel_downloads: int (Optional)
    Maximal allowed (other) downloads in parallel. If the user attempts to start more downloads in parallel than the specified limit, download is denied and an error returned.
  • streaming: boolean (Optional)
    Values: true, false
    If set to true, streams the video in a new browser tab once the link is clicked instead of triggering a file download. Default is false. Note that video players streaming the video from the URL will stream it regardless of this flag — so you don't need to enable this option just because you use the link in a video player.
  • ip: int (Optional)
    Allow only clients with the specified IP address to use the link and download the file. The IP must be specified as a 32-bit integer (example: 192.168.2.1 -> (192 << 24) | (168 << 16) | (2 << 8) | 1 = 3232236033).

Example Request ​

bash
curl -X GET \
  -H "Authorization: Bearer AUTH_TOKEN" \
  "https://api.xvid.com/v1/files/downloads/?file_id=54820cec18bac397e161aebc"

Example Response ​

Success (200 OK) ​

json
{
  "url": "https://cdn-na-east-1.xvid.com/53a1ac4914eaa8ffa4fce91b/test1.mp4?Expires=1403261471&AWSAccessKeyId=AKIAINU6WW5PT7GRJLVA&Signature=QfXTpvTzwB81EQNPttgLlUiX2JQ%3D"
}

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"
  }
}