HTTP Responses - Binary Responses

HTTP Responses / Binary Responses

The Optidash API offers the capability to receive the full binary representation of the output image directly in the response body. This feature enables you to bypass the step of downloading the processed image, allowing for direct streaming of the response to disk. To enable a Binary Response, you must configure your JSON-formatted request to include a mode parameter set to binary within the response hash. Additionally, an X-Optidash-Binary header must accompany your request.

X-Optidash-Binary: 1

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

It is important to note that, even when opting for Binary Responses, the API will continue to store the processed image in the Optidash temporary storage. A URL to access the image will still be provided in the JSON metadata. This ensures that, should the direct streaming of the API response encounter issues, you retain the ability to download the image at a later time.

For instance, if you wish to utilize the Image Fetch method to resize an image to 100×75 pixels, a sample cURL request employing a binary response is as follows:

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

Since cURL, by default, directs the output to stdout, the example demonstrates how to redirect this output, streaming the response directly to a specified file location (e.g., /location/on/disk/image.jpg).

When leveraging Binary Responses, it is advisable to use our official integrations. Unlike the basic cURL example, which indiscriminately streams all responses to disk — both successful and unsuccessful — our official integrations are designed to safeguard against undesired outcomes. For instance, they prevent the streaming of responses to disk in cases where the API returns a 422 Unprocessable Entity, averting scenarios where the intended file ends up empty.

Request Metadata in a Binary Response

Given that the response body comprises the binary data of the resulting image, both successful and failed requests will see the API return serialized JSON metadata within an HTTP header named X-Optidash-Metadata. Consequently, when working with Binary Responses, parsing the X-Optidash-Metadata header is essential to access metadata related to your request.