MediaCrush API

The MediaCrush API returns JSON on all methods. You might be interested in some of the API wrappers listed on our documentation overview.

MediaCrush also supports CORS for cross-origin requests. If you intend to use the MediaCrush API from browser JavaScript, you will want to set the X-CORS-Status header to 1. This is because browsers will errornously handle any request that returns a non-2xx status code (which the MediaCrush API frequently does). If you set this header, each JSON response will include the x-status property with the real status code.

Example:

GET /api/tVWMM_ziA3nm
X-CORS-Status: 1

{
    ...
    "x-status": 404
}

Methods

Albums

POST /api/album/create

Parameters: list, a list of MediaCrush hashes.

Returns: The hash of the album on success, an error code otherwise.

POST /api/album/create
list=LxqXxVPAvqqB,tVWMM_ziA3nm

{
    "hash": "LxqXxVPAvqqC"
}

In case of error, the response will contain an 'error' parameter and additional information if necessary.

Return codes:

HTTP code Meaning Success
200 The album was created correctly. true
404 At least one of the items in the list could not be found. false
413 An attempt was made to create an album that was too large. false
415 At least one of the items in the list is not a File (i.e, you tried to create an album that cantains an album) false

Hash information endpoints

GET /api/<hash>

Note: this method is equivalent to /<hash>.json.

Parameters: none.

Returns: information about <hash>. Please see Appendix A for reference objects for each possible type.

GET /api/CPvuR5lRhmS0

{
  "blob_type": "video",
  "compression": 8.93,
  "files": [
    {
      "file": "/CPvuR5lRhmS0.mp4",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.mp4",
      "type": "video/mp4"
    },
    {
      "file": "/CPvuR5lRhmS0.ogv",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.ogv",
      "type": "video/ogg"
    },
    {
      "file": "/CPvuR5lRhmS0.gif",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.gif",
      "type": "image/gif"
    }
  ],
  "extras": [
  ],
  "flags": {
    "autoplay": true,
    "loop": true,
    "mute": true
  },
  "metadata": {
      "dimensions": {
          "height": 281,
          "width": 500
      },
      "has_audio": false,
      "has_video": true
  },
  "original": "/CPvuR5lRhmS0.gif",
  "hash": "CPvuR5lRhmS0",
  "type": "image/gif",
}

When a file is uploaded to MediaCrush, it enters our processing pipeline. Various (lossless) tweaks and optimizations are done, and it's converted into several browser-friendly formats. All the files associated with a blob are included in the "files" array. If you wish to display a file to the user, examine the "blob_type" property, which may be "video", "audio", or "image". Iterate over the files available and choose any mimetypes that match what your platform can support.

Please note that you should not trust the value of "type". This is the original mimetype that was supplied by the user at the time of upload. MediaCrush disregards this value and examines uploaded files to determine their type empirically and updates "blob_type" accordingly before moving files into the processing pipline.

If the file is not found, you will get a dictionary like:

GET /api/CPvuR5lRhmS0

{
  "error": 404
}

GET /api/info?list=<hash>,...

Parameters: list, a comma-separated list of hashes.

Returns: a dictionary of objects. Please see Appendix A for reference objects for each possible type.

GET /api/info?list=tVWMM_ziA3nm,CPvuR5lRhmS0

{
  "CPvuR5lRhmS0": {
    "blob_type": "video",
    "compression": 8.93,
    "files": [
      {
        "file": "/CPvuR5lRhmS0.mp4",
        "url": "https://mediacru.sh/CPvuR5lRhmS0.mp4",
        "type": "video/mp4"
      },
      {
        "file": "/CPvuR5lRhmS0.ogv",
        "url": "https://mediacru.sh/CPvuR5lRhmS0.ogv",
        "type": "video/ogg"
      },
      {
        "file": "/CPvuR5lRhmS0.gif",
        "url": "https://mediacru.sh/CPvuR5lRhmS0.gif",
        "type": "image/gif"
      }
    ],
    "extras": [
    ],
    "flags": {
      "autoplay": true,
      "loop": true,
      "mute": true
    },
    "metadata": {
        "dimensions": {
            "height": 281,
            "width": 500
        },
        "has_audio": false,
        "has_video": true
    },
    "original": "/CPvuR5lRhmS0.gif",
    "hash": "CPvuR5lRhmS0",
    "type": "image/gif",
  },
  "tVWMM_ziA3nm": {
    "blob_type": "video",
    "compression": 17.99,
    "files": [
      {
        "file": "/tVWMM_ziA3nm.mp4",
        "url": "https://mediacru.sh/tVWMM_ziA3nm.mp4",
        "type": "video/mp4"
      },
      {
        "file": "/tVWMM_ziA3nm.ogv",
        "url": "https://mediacru.sh/tVWMM_ziA3nm.ogv",
        "type": "video/ogg"
      },
      {
        "file": "/tVWMM_ziA3nm.gif",
        "url": "https://mediacru.sh/tVWMM_ziA3nm.gif",
        "type": "image/gif"
      }
    ],
    "extras": [
    ],
    "flags": {
      "autoplay": true,
      "loop": true,
      "mute": true
    },
    "metadata": {
        "dimensions": {
            "height": 281,
            "width": 500
        },
        "has_audio": false,
        "has_video": true
    },
    "original": "/tVWMM_ziA3nm.gif",
    "hash": "tVWMM_ziA3nm",
    "type": "image/gif"
  }
}

POST /api/url/info

Parameters: list, a comma-separated URLs to check, or a single URL.

Returns: A dictionary mapping URLs that have been previously uploaded to MediaCrush files.

POST /api/url/info
list=http://i.imgur.com/rctIj1M.jpg,http://does.not/exist.gif

{
  "http://does.not/exist.gif": null,
  "http://i.imgur.com/rctIj1M.jpg": {
    "blob_type": "image",
    "compression": 1.0,
    "extras": [],
    "files": [
      {
        "file": "/4Gt0YcGMPA7S.jpg",
        "url": "https://mediacru.sh/4Gt0YcGMPA7S.jpg",
        "type": "image/jpeg"
      }
    ],
    "flags": {},
    "metadata": {
        "dimensions": {
            "height": 281,
            "width": 500
        },
        "has_audio": false,
        "has_video": true
    },
    "hash": "4Gt0YcGMPA7S",
    "original": "/4Gt0YcGMPA7S.jpg",
    "type": "image/jpeg"
  }
}

GET /api/<hash>/exists

Parameters: none.

Returns: a dictionary answering the question of whether a hash exists.

GET /api/XKacFeUrWuqm/exists

{
  "exists": true
}

GET /api/status?list=<hash>,...

Parameters: list, a comma-separated list of hashes.

Returns: a dictionary of objects and the status of each.

GET /api/status?list=tVWMM_ziA3nm,CPvuR5lRhmS0

{
    "tVWMM_ziA3nm": {
      "status": "processing"
    },
    "CPvuR5lRhmS0": {
      "status": "pending"
    }
}

GET /api/<hash>/status

Parameters: none.

Returns: the processing status of the file identified by <hash>.

GET /api/LxqXxVPAvqqB/status

{
  "status": "done",
  "hash": "LxqXxVPAvqqB",
  "LxqXxVPAvqqB": {
    "blob_type": "video",
    "compression": 8.93,
    "files": [
      {
        "file": "/LxqXxVPAvqqB.mp4",
        "url": "https://mediacru.sh/LxqXxVPAvqqB.mp4",
        "type": "video/mp4"
      },
      {
        "file": "/LxqXxVPAvqqB.ogv",
        "url": "https://mediacru.sh/LxqXxVPAvqqB.ogv",
        "type": "video/ogg"
      },
      {
        "file": "/LxqXxVPAvqqB.gif",
        "url": "https://mediacru.sh/LxqXxVPAvqqB.gif",
        "type": "image/gif"
      }
    ],
    "extras": [
    ],
    "flags": {
      "autoplay": true,
      "loop": true,
      "mute": true
    },
    "metadata": {
        "dimensions": {
            "height": 281,
            "width": 500
        },
        "has_audio": false,
        "has_video": true
    },
    "original": "/LxqXxVPAvqqB.gif",
    "hash": "LxqXxVPAvqqB",
    "type": "image/gif"
  }
}

Return codes:

HTTP code Meaning Success
200

The file was found.

Note: this doesn't mean that the processing succeeded. Check the table below.

true
404 There is no file with that hash. false
415 The data type associated with this hash does not accept processing. false

Possible values for status:

Value Meaning
done The file has been processed.
ready The file is still processing, but it is ready to be consumed by a web browser.
pending The is in the processing queue.
processing The file is currently being processed.
error A critical processing step finished early with an abnormal return code.
timeout The file took too long to process.
unrecognised MediaCrush does not support processing this media format.
internal_error The workers died unexpectedly. The client is advised to try again.

Notes:

The "result" object will only be included if the status is "done".

GET /api/<hash>/flags

Parameters: none.

Returns: the dictionary of flags pertaining to hash.

GET /api/Ta-nbchtCw6d/flags

{
  "flags": {
    "autoplay": true,
    "loop": true,
    "mute": true
  }
}

Return codes:

HTTP code Meaning
404 There is no file with that hash.
200 The file was found.

Hash manipulation endpoints

POST /api/<hash>/flags

Parameters: the flags that are to be changed, with a value of true to activate a flag and false to deactivate it.

Returns: the dictionary of flags pertaining to hash.

POST /api/Ta-nbchtCw6d/flags
autoplay=false&mute=false

{
  "flags": {
    "autoplay": false,
    "loop": true,
    "mute": false
  }
}

Return codes:

HTTP code Meaning Success
200 The IP matches the stored hash and the flags have been updated. true
401 The IP does not match the stored hash. false
404 There is no such hash. false
415 One of the parameters passed to this endpoint is not recognised. Ensure your form data does not contain extraneous fields. false

DELETE /api/<hash>

Parameters: none.

Returns: a dictionary describing whether the delete operation succeeded. In most cases it is easier to check the HTTP status code.

DELETE /api/CPvuR5lRhmS0

{
  "status": "success"
}

If the request is unsuccessful, you will get a response like:

DELETE /api/CPvuR5lRhmS0/delete

{
  "error": 401
}

Return codes:

HTTP code Meaning Success
200 The IP matches the stored hash and the file (if applicable) was deleted. true
401 The IP does not match the stored hash. false
404 There is no such hash. false

POST /api/upload/file

Parameters: file, the file to upload.

Returns: a dictionary with the hash of the file in case the upload succeeded, a dictionary containing the error code if it did not succeed.

curl -F file=@/tmp/cat.gif /api/upload/file

{
  "hash": "LxqXxVPAvqqB"
}

In case of error, the response will contain an 'error' parameter and additional information if necessary.

curl -F file=@/tmp/cat.gif /api/upload/file

{
  "error": 409,
  "hash": "LxqXxVPAvqqB",
  "LxqXxVPAvqqB": {
    "blob_type": "video",
    "compression": 0.0,
    "files": [
      {
        "file": "/LxqXxVPAvqqB.png",
        "url": "https://mediacru.sh/LxqXxVPAvqqB.png",
        "type": "image/png"
      }
    ],
    "metadata": {
        "dimensions": {
            "height": 281,
            "width": 500
        },
        "has_audio": false,
        "has_video": true
    },
    "extras": [
    ],
    "original": "/LxqXxVPAvqqB.png",
    "hash": "LxqXxVPAvqqB",
    "type": "image/png"
  }
}

Return codes:

HTTP code Meaning Success
200 The file was uploaded correctly. true
409 The file was already uploaded. true
420 The rate limit was exceeded. Enhance your calm. false
415 The file extension is not acceptable. false

POST /api/upload/url

Parameters: url, the URL from where to fetch the file to upload.

Returns: the same as /api/upload/file.

Return codes:

HTTP code Meaning Success
200 The file was uploaded correctly. true
400 The URL is invalid. false
404 The requested file does not exist. false
409 The file was already uploaded. true
415 The file extension is not acceptable. false
420 The rate limit was exceeded. Enhance your calm. false

Appendix A - Example objects

File

{
  "blob_type": "video",
  "compression": 8.93,
  "files": [
    {
      "file": "/CPvuR5lRhmS0.mp4",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.mp4",
      "type": "video/mp4"
    },
    {
      "file": "/CPvuR5lRhmS0.ogv",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.ogv",
      "type": "video/ogg"
    },
    {
      "file": "/CPvuR5lRhmS0.gif",
      "url": "https://mediacru.sh/CPvuR5lRhmS0.gif",
      "type": "image/gif"
    }
  ],
  "extras": [
  ],
  "metadata": {
      "dimensions": {
          "height": 281,
          "width": 500
      },
      "has_audio": false,
      "has_video": true
  },
  "flags": {
    "autoplay": true,
    "loop": true,
    "mute": true
  },
  "original": "/CPvuR5lRhmS0.gif",
  "hash": "CPvuR5lRhmS0",
  "type": "image/gif"
}

When a file is uploaded to MediaCrush, several associated files may be generated. In the case of GIF files, two video files are generated - one with h.264/mpeg and another with theora/vorbis. Some media will also have "extra" files. In the case of uploaded videos, we'll include an image/png thumbnail file in the extras. Your application should prefer the url of a file over the file, because it will be loaded via our CDN (which will be much faster).

Description of fields:

Album

{
  "files": [
    {
      "blob_type": "video",
      "compression": 0.0,
      "extras": [],
      "metadata": {
          "dimensions": {
              "height": 281,
              "width": 500
          },
          "has_audio": false,
          "has_video": true
      },
      "files": [
        {
          "file": "/yOEHB2vDiWS-.jpe",
          "type": "image/jpeg"
        }
      ],
      "original": "/yOEHB2vDiWS-.jpe",
      "type": "image/jpeg"
    },
    {
      "blob_type": "video",
      "compression": 0.0,
      "extras": [],
      "files": [
        {
          "file": "/vLGcgr9eXhsH.jpe",
          "type": "image/jpeg"
        }
      ],
      "metadata": {
          "dimensions": {
              "height": 281,
              "width": 500
          },
          "has_audio": false,
          "has_video": true
      },
      "original": "/vLGcgr9eXhsH.jpe",
      "type": "image/jpeg"
    },
    {
      "blob_type": "video",
      "compression": 0.0,
      "extras": [],
      "files": [
        {
          "file": "/uEKCcQyLVci7.jpe",
          "type": "image/jpeg"
        }
      ],
      "metadata": {
          "dimensions": {
              "height": 281,
              "width": 500
          },
          "has_audio": false,
          "has_video": true
      },
      "original": "/uEKCcQyLVci7.jpe",
      "type": "image/jpeg"
    }
  ],
  "hash": "6ecd2bbd34ec",
  "type": "application/album"
}

Appendix B - Flags by blob_type

These flag listings specify all the possible flags that may be returned in an object. However, some or all of the flags may be unavailable.

video

{
    "autoplay": true,
    "loop": true,
    "mute": true
}
How are we doing?
Send feedback