Upload via custom path

Last updated Apr 21, 2026 You can use a custom ID path to upload an image instead of the path automatically generated by Cloudflare Images’ Universal Unique Identifier (UUID).

Custom paths support:

Note

Images with custom ID paths cannot be made private using signed URL tokens. Additionally, when serving images, any % characters present in Custom IDs must be encoded to %25 in the image delivery URLs.

Make a POST request using the example below as reference. You can use custom ID paths when you upload via a URL or with a direct file upload.

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>'

After successfully uploading the image, you will receive a response similar to the example below.

{
    "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": []
}

Was this helpful?

YesNo

On this page

Upload via custom path - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/images/storage/upload-images/upload-custom-path/#page","headline":"Upload via custom path","description":"Assign a custom ID path when uploading images to Cloudflare Images instead of using an auto-generated UUID.","url":"https://developers.cloudflare.com/images/storage/upload-images/upload-custom-path/","inLanguage":"en","image":"https://developers.cloudflare.com/images/storage/upload-images/upload-custom-path/og.png?v=5d05d712e51a73db","dateModified":"2026-04-21","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Learn how to upload images to Cloudflare using Workers. This guide provides code examples for uploading both standard and AI-generated images efficiently. title: Upload via a Worker image: https://developers.cloudflare.com/images/storage/upload-images/upload-file-worker/og.png?v=1e85de6fb63abadc

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/images/llms.txt
Use this file to discover all available pages before exploring further.