Cloudflare Docs
Cloudflare Image Optimization
Visit Cloudflare Image Optimization on GitHub
Set theme to dark (⇧+D)

Custom ID

You can use a custom path to upload images to Cloudflare Images, instead of the path automatically generated by Cloudflare Images’ Universal Unique Identifier (UUID). The custom path has the following properties:

Below is an example of the custom ID feature using upload via URL:

curl --request POST<​​ACCOUNT_ID>/images/v1 \
--header 'Authorization: Bearer <API_TOKEN>' \
--form 'url=https://<REMOTE_PATH_TO_IMAGE>' \
--form 'id=<PATH_TO_YOUR_IMAGE>'

You can also use the custom ID feature with direct file upload:

curl --request POST \<ACCOUNT_ID>/images/v1 \
--header 'Authorization: Bearer <API_TOKEN>' \
--form 'file=@./<PATH_TO_YOUR_IMAGE>' \
--form 'id=<PATH_TO_YOUR_IMAGE>'

You will then receive a response similar to this:

"result": {
"filename": "<YOUR_IMAGE>",
"uploaded": "2022-04-20T09:51:09.559Z",
"requireSignedURLs": false,
"variants": ["<PATH_TO_YOUR_IMAGE>/public"]
"result_info": null,
"success": true,
"errors": [],
"messages": []

You can use the custom ID feature with the ability to serve images from custom domains for added flexibility.

Refer to Make your first API request to learn more about API tokens.

​​ Custom IDs in delivery URLs

When serving images, you can include non URL-encoded Custom IDs directly in the image URLs. However, any % characters present in Custom IDs must be encoded to %25 in the image delivery URLs.

​​ Custom IDs and private images

Images with a custom ID cannot be made private using signed URL tokens.