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:

• Can be up to 1024 characters long.
• Can include any number of subpaths.
• Supports the UTF-8 encoding standard Open external link for characters.

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

curl --request POST https://api.cloudflare.com/client/v4/accounts/<​​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 \
  https://api.cloudflare.com/client/v4/accounts/<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": {
    "id": "<PATH_TO_YOUR_IMAGE>",
    "filename": "<YOUR_IMAGE>",
    "uploaded": "2022-04-20T09:51:09.559Z",
    "requireSignedURLs": false,
    "variants": ["https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/<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.