Getting Started with Cloudflare Images

Getting Started with Cloudflare Images

As developers, there are so many things that bring us joy: new VS Code extensions that improve our productivity, setting up a third or even fourth monitor, and our code compiling on the first try, to name a few. But just as there are many things that bring us joy, there are a few that are the bane of our existence: working with timezones, vertical centering HTML content without flexbox, and handling uploading images.

In this post, we'll learn how handling uploading images with Cloudflare Images can be a joyous experience. Let's get into it.

Cloudflare Images is a new feature launched by the good folks at Cloudflare. If you're not familiar with Cloudflare, they are a web platform that offers everything from CDN solutions to serverless functions with Cloudflare Workers, JAMStack like static site hosting with Cloudflare Pages, and much more. Their goal is to help build a better Internet and I've been a huge fan since the very beginning.

Cloudflare Images

Cloudflare Images is Cloudflare's take on the management, uploading, and hosting of images for your applications. The feature just recently became available for everyone to try and having spent a bit of time with it, I really like what I'm seeing. They have made the process of uploading and working with images much better. In this post, I'll show you how.

To get started with Cloudflare Images, you'll need a free Cloudflare account. You can sign up at To use Cloudflare Images, you do not have to move your domain to Cloudflare. Images is a separate and stand-alone product. From the main menu, simply select Images and you'll be ready to go.

Getting Started with Cloudflare Images

Once you click the Images link, you'll be taken to the Cloudflare Images onboarding experience.

One of the things I really like about Cloudflare Images is their transparent pricing. The pricing works like this: You pay a predefined amount for the number of images stored, and then you pay a usage-based fee based on how often those images are served.

Cloudflare Images pricing

The pricing starts at $5 USD for 100,000 images and $1 per 100,000 images served. I think this pricing is very fair compared to other providers, but I do wish there was a free tier to allow you to try Cloudflare Images without giving them a credit card. From this screen, hit Continue to configure your storage.

Cloudflare Images pricing selection

For this tutorial, I'm going to go with the smallest tier, and I'd recommend starting with the smallest tier, as you can always change it as your needs evolve. Once you've set up billing, you will be greeted with the Cloudflare Images dashboard:

Cloudflare Images dashboard

And you're all set. From here on out, you have access to Cloudflare Images and can upload and serve images right away.

To test our functionality, let's go ahead and use the Quick Upload feature to upload a single image and test it out. Just drag and drop an image onto the quick upload area and the image will be automatically uploaded.

We can click the image to preview it, and the image I uploaded is displayed:

Cloudflare Images preview

The Image URL will be the live URL you can use to access the image. Let's go ahead and open that link in our browser to make sure it works as well. And as expected, it does:

Cloudflare Images browser access

While we can upload all of our images manually using the Cloudflare Images dashboard, it's probably not the most efficient way to do things. Cloudflare has an excellent API that will allow us to upload our images and in this section, I'll show you how to do just that.

In the Cloudflare Images dashboard, navigate to the Use API tab. Here, you'll see how you can utilize the Cloudflare Images API to upload images. The gist of it is that we will be making a POST request to the{YOUR-CLOUDFLARE-ACCOUNT}/images/v1 API endpoint. We'll pass our file that we wish to upload as well as an API token to verify our identity and ensure we have the right permission to do this action.

The first thing we'll need to do is create an API token for working with Cloudflare Images. Click on the "Get an API token here" link to get started. This will take you to the Cloudflare API tokens dashboard. When you get to this dashboard, click on the Create Token button.

Cloudflare API Tokens dashboard

We'll need to name our token, and you can name it whatever you prefer. I'll name my token "Cloudflare Images API." For the permissions, I'll give Account-based permissions to the Cloudflare Images service and the level of access will be Edit. I'll leave everything else as default, but you can scope it down even further to suit your needs.

Setup Cloudflare Images token

Once our token is created, we can test it by running a cURL command. Let's do that.

Verify Cloudflare Images token

Open up your terminal of choice that has cURL installed and copy and paste the above command. If everything works as expected, you should get a response like this:

  "result": {
    "id" : "a4723915b9913c8df5d11d3c32e2ffb0",
      "message":"This API Token is valid and active",

If you get a successful response, you are good to go. If not, I suggest going back and following the directions on how to create the token more closely. Make a note of the API token. You'll need it shortly.

With a newly minted API token that can write to Cloudflare Images, let's go back to our Cloudflare Images dashboard and to the "Use API" tab. Insert your API token in the provided field. For the Image File Name, add a file name of an image that you wish to upload from your device. In my case, I have a picture of Chris and Kapehe that I want to upload.

Inputting the file name will generate the cURL command you'll need to execute to programmatically upload the image.

Generate Cloudflare Images cURL command

Let's copy this cURL command and go back to our terminal window and run it. Please note that for the file name, it has to be a file that exists and is an image—either a JPG, PNG, GIF, or Web-P. Additionally, ensure that the directory you run the cURL command in has that image, or you have the proper path to it.

For me, I'll be running the command from my desktop folder where the image is placed, so the command will look like this:

curl -X POST -F file=@./chris-kapehe.jpg -H "Authorization: Bearer {API-TOKEN}"{ACCOUNT-ID}/images/v1

Execute the command, and if successful, you'll get a response such as this:

Upload to Cloudflare Images via cURL

To confirm that the upload was successful, let's go back to the Cloudflare Images dashboard and verify that our file is there. If it is, open it up to confirm that the right file was uploaded.

Verify image uploaded to Cloudflare Images

It was!

While cURL is a step up to manually uploading images using the Cloudflare Images dashboard, it's still not the most ideal way to upload images. Let's take it a step further and show how you can upload images to Cloudflare Images with NodeJS. We'll keep this example fairly short and won't go into all the nuances of file uploads, but it should be enough to get you started.

Let's start with installing our dependencies:

npm i express formidable axios form-data

Create a new file and call it server.js. In this file, let's set up our skelton application.

// server.js

const express = require("express");
const formidable = require("formidable");
const fs = require("fs");
const axios = require("axios");
var FormData = require("form-data");

const app = express();"/upload", async (req, res) => {});

app.listen(3000, () => console.log("Example app listening on port 3000!"));

Our app is using Express and we are setting up a single route called /upload which will handle uploading our images to Cloudflare Images. The /upload route only accepts POST requests, so if you start up the server and navigate to your browser at localhost:3000/upload, you won't see anything. Rather than build a UI, we'll use Postman to simulate accessing our app from an application. But we're getting ahead of ourselves. Let's build out the logic to process our image and upload it to Cloudflare Images.

// server.js

const express = require("express");
const formidable = require("formidable");
const fs = require("fs");
const axios = require("axios");
var FormData = require("form-data");

const app = express();"/upload", async (req, res) => {
  // We're using formidable to capture our form contents
  const form = new formidable.IncomingForm();

  // We'll parse the contents of the form that gets sent to our endpoint
  form.parse(req, function (err, fields, files) {
    // We'll expect a file called myFile and create a readable stream from its temporary path.
    // myFile will be the picture we want to upload
    let image = fs.createReadStream(files.myFile.path);

    //We'll create a new form to send to Cloudflare Images and append our newly processed image
    var data = new FormData();
    data.append("file", image);

    // Finally, we'll use axios to make a POST request to Cloudflare Images
      method: "post",
      url: "{YOUR-CLOUDFLARE-ACCOUNT-ID}/images/v1",
      headers: {
        Authorization: `Bearer {YOUR-API-TOKEN}`,,
      data: data,
    }).then(() => {
      console.log("Upload Successful");
      res.json({ message: "Success" });

app.listen(3000, () => console.log("Example app listening on port 3000!"));

The code above is commented, but to give a brief rundown of what happens:

  • We'll send an image we want to upload to Cloudflare Images via Postman.
  • We'll process the form we receive and extract the image out of it.
  • We'll prepare a new form to send to Cloudflare Images.
  • We'll make the request to Cloudflare Images via axios, passing our Authorization token to verify our identity.

Let's try it out. Start up the server by running node server.js. Open up Postman, point it to localhost:3000/upload, set the body to send form-data, and finally name the key myFile and change the type to "File." Select an image to upload for the value and hit "Send."

Upload to Cloudflare Images from Postman

If all goes well, you should receive a success message, meaning that the image was successfully uploaded to Cloudflare Images. Head over to the Cloudflare Images dashboard and verify that the image is there. In my case, it was, and the image is below:

Upload to Cloudflare Images from Postman result

One thing to note is that the file name will be different from the file name you sent from Postman. The reason for this is we're just using the temporary path name when we prepare the image for Cloudflare Images. You could modify this if you wanted to get the exact filename.

Cloudflare Images provides a simple yet powerful API for uploading and serving images for your applications. Cloudflare's infrastructure is massive and images uploaded to it will load super quickly. There is a lot more we can talk about with Cloudflare Images, such as image variants that allow you to server the right image at the right size for the right purpose, protecting the images so only privileged users or apps can access them, and a direct upload option that can forgo needing a back end to upload images. We'll save those topics for another time.

Happy uploading.