What are image versions?

The version of an image is the timestamp of uploading the image (e.g., v1366687335). It is required for building URLs of the latest uploaded version of an image in case that multiple images were uploaded sharing the same public ID (overwriting a previously uploaded image). It allows bypassing a previously cached version of the image. 
Each image (public ID) has only the latest uploaded version available for delivery and transformation. The version value is included in the response of our upload API call.

Here's a sample URL with the version component:

http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg

Cloudinary's does not require the version component to be present in URLs (but you might get a previously cached version in this case). For example:

http://res.cloudinary.com/demo/image/upload/sample.jpg

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

http://res.cloudinary.com/demo/image/upload/v1/sample_folder/sample_name.jpg
Have more questions? Submit a request

Comments

  • 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:

    http://res.cloudinary.com/<your\_cloud\_name>/image/upload/v1364158979/multiple/folders/sample.jpg

    Here's a code example in .NET:

    @Model.Cloudinary.Api.UrlImgUp.Version("1364158979").BuildImageTag("multiple/folders/sample.jpg")

  • 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):

    http://cloudinary.com/documentation/java_additional_topics#admin_api

    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):

    http://res.cloudinary.com/demo/image/upload/sample.jpg

    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

    Hello,

    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

    cloudinary.url().secure(true).format("jpg").generate("public-id-of-image");


    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,
    cloudinary.url().version().secure(true).format("jpg").generate("public-id-of-image");

Powered by Zendesk