What are image versions?




  • Avatar
    Michael Binks

    If we have an image that has been uploaded/overwritten numerous times it will have an updated version number. If the image also includes a '/' within its public id and we retrieve the image using the shortened v1 method  in the url will we be guaranteed to get the latest version?

  • Avatar
    Itay Taragano

    Hi Michael,

    For images within folders (or any images which their public IDs include the '/' character), due to technical reasons related to naming convention, Cloudinary's integration libraries automatically add the 'v1' parameter. However, to bypass CDN cache, and forcing delivery of the newest image, the version component must be added.

    For example, if the latest image's version is '1364158979' (The  version  parameter is returned with every upload call), then a URL like the following should be used:


    Here's a code example in .NET:


  • Avatar
    Jeff Terrell

    Orly, you say that the version value of an image is included in the response of your upload API call.  This makes sense, and I see this behavior in my app.

    My question is: can this information be retrieved from the API (or, more specifically, from the Java library) apart from an upload call?

    Here's my use case.  I store images using a public ID derived from the ID of an account in the database.  For example, a company's logo might have the public ID company/1/logo if their internal ID is 1.  The point is, I don't save any information in my database about the public ID of their logo image.  So, when that image needs to change, I re-upload a new image with the same public ID.  Because this change takes a while to propagate through the various layers of caching, they will continue to see the old image for a while, unless I give them the URL of the *versioned* image instead of the default URL.

    So, is there a way to get the URL of the versioned image without saving information from the upload request?  Thanks for your help.

  • Avatar
    Itay Taragano

    Hi Jeff,

    While we warmly recommend to also store the 'version' value returned by every upload call in your database, you can use the Admin API to get full details of your resources, including the version parameter and the url parameter (which already includes the 'version' component).

    For more information (in JAVA):


    Note that in default the Admin API is rate limited to 500 calls per hour (12,000 daily).

  • Avatar
    Adam Taylor

    Can I just confirm two things:

    • The version of an image is never updated unless a new image is uploaded, which explicitly uses the same public ID.
    • Leaving out the version from a URL is functionally equivalent to sending "/v1" as part of the URL and there is no advantage to either format.

    Are they correct? Thanks!

  • Avatar
    Itay Taragano

    Hi Adam,

    While you're basically correct, please allow me to further explain.

    Let's say you use a URL like the following to deliver your image (without the version component):


    If you're not planning on overriding the image, the version component is optional, hence - you can deliver the image without the version value as part of the URL (even without 'v1') and the image will be delivered as usual.

    On the other hand, when you do override the image (e.g., upload a new image while setting its public ID to be the same as the already stored image), the image is updated in your Cloudinary account, but if you access the exact same URL you might be still getting the older (CDN cached) version of the image.

    Therefore, the solution for this is to alter the URL so that you can still access the same public ID of your Cloudinary account, while also bypass the cached CDN versions and force the delivery of the newest image.

    For this to happen you should use a unique URL which isn't cached in the CDN, e.g., a URL which was not yet accessed. If the URL with 'v1' was never accessed before, then adding 'v1' would deliver the newer version.

    In order to avoid keeping track of which version value was accessed before or not, Cloudinary helps you keeping the version value unique with every re-upload of the image. The updated version value is returned with each upload (the version value is a representation of the upload's timestamp). Updating the URL to use the new version value will ensure that you have the latest version of the image.

    I hope that helps.

  • Avatar
    David Wood

    That helps Itay!

    Can I ask for one further clarification, so I can be sure I understand what's going on:

    The point of using the version is to use it to "cache bust" - to make sure the URL is new and therefore cause the cache to refresh. So, naively, you could use any random version number, and assuming that the CDN had never been asked for that version number previously, it would dump its cached copy and refresh from the main Cloudinary store.

    Which would be pointless of course because that would mean the CDN would always refresh (because the URL always contained a random version).

    So by using the actual latest version number, you ensure a CDN cache refresh when it is needed, and then in the future, when your request that same (latest) version again, you get a cached copy (thereby taking advantage of the CDN cache).

    What it does not do, is allow you to access an earlier version. Requesting an earlier version might get you that earlier version for a while, until the CDN cache is refreshed, but you can't go back through the history of the versions by passing earlier version IDs.

    Is that right?

  • Avatar
    Itay Taragano

    Yes David, that is correct.

    Note that images are cached for one month. So after a full month has passed, all earlier versions of the image will be gone.

    If having access to an earlier version of the image is something that you require, you should probably consider to not override the image in the first place and maybe use a new public ID when re-uploading.

  • Avatar
    Anup Sarode


    I'm using Android library. While I fetch the URL using the following code, I dont' get the version number and hence I don't get the latest image but the cached one. How can I get the latest image URL? I don't want to provide the version number explicitly myself but to fetch it.

    Android Code


    Response - https://res.cloudinary.com/13568798jhk/v1429795291/ojpz1z9xfpwszka23thc.jpg

  • Avatar
    Maor Gariv

    Sorry for the very late reply, we have noticed that this request was left unattended. I guess this is not relevant anymore but for future reference -

    You can specify the version number by adding it as a parameter. For example,

  • Avatar
    VersionPress Team

    > However, if your public ID includes folders (elements divided by '/'), the version component is mandatory, but you can make it shorter.


    Is this still true? We use folders and it seems that images in folders work even without the version segment in the URL.

  • Avatar
    Stephen Doyle

    While serving images is possible in folders without use of a version segment in the URL, we state that it's mandatory because if it's excluded there are side-effects related to caching and invalidation which may not be desirable.

    In particular, if you use a URL structure with folders but without a version component, when you replace an image with a newer version, the old URL won't be invalidated on the CDN, and users may see the old version until the cache expires.

    For more information please see 'asset versions' in the upload documentation or the section in the same document which discusses 'invalidating cached assets in the CDN'

  • Avatar
    Mike Grushin



    What would this look like for jQuery or JS version?

    Thank you,



  • Avatar
    Marissa Masangcay

    Hi Mike,

    Here is the equivalent call in jQuery:

    $.cloudinary.imageTag("sample", { version: 12345678, secure: true, format: 'jpg'});

    That would generate the following URL:


    Hope this helps!

  • Avatar

    Hi Marissa Masangcay, 

    How will the below be in python?

    $.cloudinary.imageTag("sample", { version: 12345678, secure: true, format: 'jpg'});
  • Avatar
    Raz Ziv

    Hi Arun,

    If you would like to only generate the delivery URL in Python you should use the following:

    cloudinary.utils.cloudinary_url("sample", version=12345678, secure=True, format="jpg")

    Alternatively, if you prefer generating the entire HTML Image tag, you can use the below example:

    cloudinary.CloudinaryImage("sample").image(version=12345678, secure=True, format="jpg")
  • Avatar

    Hi Raz, 

    As per your advise i used the below command but the link i got is not available.


    Kindly help me

    I actually want one url that can be updated with different images, yet the url has to be same.


  • Avatar
    Raz Ziv

    Hi Arun,

    Is it possible that you're passing "content/abc_cropped-2.jpg" as the public_id instead of just "content/abc_cropped-2"?

    The public_id should not consist of the image extension. As you can see, this causes the generated URL to have twice the jpg extension and therefore you get a 404 error as such an image does not exist.

    If you still encounter any issues, please open a support ticket at support@cloudinary.com and we will further assist you in resolving them.

Please sign in to leave a comment.