Some of imgix's most powerful features, like watermarks and multiline text, require passing in a URL or a text string as the value of a parameter. For these parameters, we've recommended that both URLs and strings be URI-encoded.
Today we're announcing Base64 encoding support for these parameters, to ensure that they resolve correctly even when nested several levels deep. This makes doing complex composting with imgix more reliable and easier to implement.
For example, to add a watermark, you would grab the URL of the graphic that you're using for the mark, encode it, and then make the encoded URL the value of mark.
Base Image
https://assets.imgix.net/examples/blueberries.jpg
w=800
h=300
fit=crop
markscale=25
markpad=10
markalign=center,middle
mark=* (see parameters below)
Watermark Image
https://assets.imgix.net/presskit/imgix-presskit.pdf?page=4&fm=png&w=320&dpr=2&q=100
page=4
fm=png
w=320
dpr=2
q=100
In this example, the entire watermark URL must be pre-encoded before being passed to the mark parameter, so the final URL for the watermarked image looks like this:
https://assets.imgix.net/examples/blueberries.jpg?w=800&h=300&fit=crop&markscale=25&markpad=10&markalign=center%2Cmiddle&mark=https%3A%2F%2Fassets.imgix.net%2Fpresskit%2Fimgix-presskit.pdf%3Fpage%3D4%26fm%3Dpng%26w%3D320%26dpr%3D2%26q%3D100
New Base64 Support
That all works fine with standard URI-encoding, but adding text into the mix can be a bit tricky in these nested multi-layer compositions. Unless generated carefully, the need to encode the text and then encode the URL that it's part of could end up displaying the codes rather than the text.
To remove this issue, we've added Base64 encoding support to all parameters. To use it, add 64 to the parameter name, then Base64-encode the URL or text string and add it as the parameter value. This will be particularly useful for the following parameters, which often include user-generated text or comma-separated values.
So, for example, if we wanted to add a line of text at the bottom of the image using the Typesetting Endpoint, we need to create the text URL, encode it, and then add it as the value of blend (because mark has already been used). However, the emoji, spaces, and comma-separated value of txtalign would have been potentially problematic with standard URI encoding when passed to another parameter.
https%3A%2F%2Fassets.imgix.net%2F~text%3Ftxt%3DBlueberries%20are%20cool!%20%F0%9F%98%8E%26txtclr%3Dfff%26%26txtshad%3D10%26txtsize%3D30%26txtfont%3DAvenir-Black%26txtalign%3Dcenter%2Cbottom%26w%3D600
However, with Base64 encoding, all such URLs are completely safe and nestable. The link above will become the following when Base64-encoded instead, and can then be passed safely to the blend64 parameter:
aHR0cHM6Ly9hc3NldHMuaW1naXgubmV0L350ZXh0P3R4dD1CbHVlYmVycmllcyBhcmUgY29vbCEg8J-YjiZ0eHRjbHI9ZmZmJiZ0eHRzaGFkPTEwJnR4dHNpemU9MzAmdHh0Zm9udD1BdmVuaXItQmxhY2smdHh0YWxpZ249Y2VudGVyLGJvdHRvbSZ3PTYwMA
The final URL, with the text added and Base64 on all relevant parameters, would look like this:
https://assets.imgix.net/examples/blueberries.jpg?w=800&h=300&fit=crop&markscale=25&markpad=10&markalign64=Y2VudGVyLG1pZGRsZQ&mark64=aHR0cHM6Ly9hc3NldHMuaW1naXgubmV0L3ByZXNza2l0L2ltZ2l4LXByZXNza2l0LnBkZj9wYWdlPTQmZm09cG5nJnc9MzIwJmRwcj0yJnE9MTAw&blend64=aHR0cHM6Ly9hc3NldHMuaW1naXgubmV0L350ZXh0P3R4dD1CbHVlYmVycmllcyBhcmUgY29vbCEg8J-YjiZ0eHRjbHI9OTljJnR4dHNpemU9MjQmdHh0Zm9udD1BdmVuaXItQmxhY2smdHh0YWxpZ249Y2VudGVyLGJvdHRvbSZ3PTYwMA&ba=Y2VudGVyLGJvdHRvbQ
which results in the final image:
Generating Base64-encoded parameters is easy in many languages, and the imgix client libraries are being updated to automatically encode strings passed to Base64 variant parameters. Check whichever library you’re using for specific details of its implementation. We use the URL-safe alphabet for Base64 encoding.
See the Image URL API documentation for more information about our Base64 encoding support.
