An API to convert any image into ASCII

Girl with the pearl earing ASCII


Who doesn’t love ASCII art?

There are the true artists who create art themselves, a character at a time. For the rest of us, there are lots of great ASCII art generators, for instance Picascii or Text Image.  One thing they are missing though is an API to handle the image-to-ASCII conversion.  When we were building our API for image transformations, we had to include things like resize, compress, and crop but we wanted to include ASCII because it’s just awesome. This post is about this cool feature. As you’ll see, with this online tool that works as a png converter, modifying image files has never  been easier.

This blog will convert an jpg to ASCII in the example, but you can also automatically convert the following file types to ASCII using our API: png, ai, psd, tiff, bmp.

Let’s go!

The Filestack transformation API

The Filestack transformation API is really simple to use.  Basically, you send a request to our transformation endpoint along with your API key and task.  You can programmatically interact with our API, but in these examples, I’ll just show you how to convert to ASCII by adding conversion tasks to at URL.

Here is how the Transformation URL is structured for an image hosted on some server or object store like Amazon S3.

You can see there are three parts: your API key, the conversion task (in our case convert-to-ascii), and the url of the image we want to convert.

Screen Shot 2017-01-26 at 10.33.56 AM

How to convert any image into an HTML file of ASCII Art

Ok, with the basics out of the way, let’s see how the Filestack transformation engine can take any image file and turn it into an HTML file of ASCII Art by simply passing these few url parameters to the Filestack API.

Here is the structure of the Image to ASCII task.

Image to ASCII Task URL Format:<API_KEY>/ascii=[options]/File_URL

File_URL is the url of the image that you want to convert.  This could be any image hosted on any server, but most commonly will be something stored on an object store like S3, Azure Blob store or Google Storage.

The options are:

ascii=background:white or #FF0000

where you specify a background color for the HTML file from our list of accepted color names or a hex color code. You can even opt for a transparent background if that is what you like.

Same thing goes for the foreground color.

ascii=foreground:red or #FF0000

This is the font color that will make up the image.  Specifying the foreground option will create a single color image.

If you want a multi-color image, you can use the colored option.


When set to true, this reproduces the colors in the original image. This works best with a dark HMTL background as you’ll see below.

You can also use the size attribute to specify the size of the returned file as a percentage of the original. The parameter must be an integer between 10 and 100. The default is 100. This online tools makes it easier for you to format image files to your own needs and expectations.

ascii=size:10 to 100

You can also reverse the character set used to generate the ASCII output. This works well with dark backgrounds and requires color:true


With the details out of the way.  Let’s look at some of the world’s most famous paintings as ASCII art!

In no particular order, here are some of the world’s most famous paintings in ASCII.  If you don’t see the ones you would have picked, give it a try and Tweet us a link via Twitter.

(BTW, for display purposes on the blog, I’ve included the ASCII as images, but if you click on each image itself, you’ll get the full HTML page with the ASCII art.  For comparison, you can click on the hyperlink to see the original.)

The great wave off of Kanazawa Hokusai ASCII


Screen Shot 2017-01-27 at 3.10.33 PM


Self portrait Frida Kahlo ASCII



American Gothic Grant Wood ASCII


Mona Lisa Leonardo Da Vinci ASCII


Van Gogh Starry Night ASCII


The Scream Edvard Munch ASCII


The persistence of memory Salvador Dali ASCII

What else can I do?

Filestack does a lot of other image transformations, using the same patterns as above. Here is a complete list of all the transformations that Filestack can do, with a link to the relevant page in documentation:

Facial Detection
Border and Effects
Image Enhancements
URL Screenshot
Image to ASCII
File type conversions

I hope that this has given you a taste of some fun, and sometimes even useful, things Filestack can do.  Till next time.

Michael @ Filestack


Read More →