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 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
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
.
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.