HTTP Responses - Binary Responses

HTTP Responses / Binary Responses

The Optidash API gives you the option to receive a full binary representation of the output (resulting) image as a response body. That way you can skip downloading the processed image and instead stream the response directly to disk. To use a Binary Response you must set the mode parameter to binary within the response hash in your JSON-formatted request and also send a X-Optidash-Binary header along with your request.

X-Optidash-Binary: 1

    "response": {
        "mode": "binary"

It's worth noting that even when Binary Responses are in use, the API will still store the resulting image in Optidash temporary storage and provide you with an image URL in JSON metadata. So even if you fail to stream back the API response (the resulting image), you will still have the option to download that image later on.

Let's assume you'd like to use the Image Fetch method (provide an image URL) and resize the image to 100×75 pixels. An example cURL request using a binary response will look like the following:

curl -X POST -u your-api-key: \
-H "Content-Type: application/json" \
-H "X-Optidash-Binary: 1" \
-d '{
    "url": "",
    "resize": {
        "width": 100,
        "height": 75
    "response": {
        "mode": "binary"
}' > /location/on/disk/image.jpg

As cURL by default sends the output to stdout, in the last line of the above example we redirect stdout and stream the response to a file /location/on/disk/image.jpg.

When using Binary Responses it is best to always rely on our official integrations as the above cURL example will stream all responses to disk (both successful AND unsuccessful). For example, when the API responds with 422 Unprocessable Entity, your /location/on/disk/image.jpg will be an empty file when using cURL from the command line. All of our official integrations guard against that behaviour and only stream the response to disk when the API responds with 200 OK.

Request Metadata in a Binary Response

Because the response body will consist of a binary representation of the resulting image, for both successful and failed requests, the API will return serialized JSON metadata in a HTTP header named X-Optidash-Metadata. In other words, when using Binary Responses, you must always parse the X-Optidash-Metadata response header to get the metadata pertaining to your request.