The version of an image is the timestamp of when the image was last updated (e.g., v1366687335). It is used when building URLs to ensure that the latest version of an image is requested, in case the image was recently overwritten and the old version is stored in a CDN or browser cache. By using versions in your delivery URLs it ensures that your application's users are always requesting the newest copy of the asset.
Each asset (public ID) has only the latest uploaded version available for delivery and transformation, and the version number you should use in your URLs is included in the response of our upload API calls and in our Media Library.
Here's a sample URL with the version component:
http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg
Cloudinary does not require the version component to be present in URLs, and it can be removed if you don't want to use that when building your URLs.
For example:
http://res.cloudinary.com/demo/image/upload/sample.jpg
If you do use versions in your URLs, it's important to keep the version that you add to your URLs up to date with the asset's current version if you overwrite it; otherwise you may encounter incorrect caching behaviour in CDNs, proxy servers, or a user's device or browser cache
For more information:
https://cloudinary.com/documentation/advanced_url_delivery_options#asset_versions
Comments
18 comments
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?
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
versionparameter 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")
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/logoif 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.
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
versionparameter and theurlparameter (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).
Can I just confirm two things:
Are they correct? Thanks!
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.
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?
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.
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
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(123456789).secure(true).format("jpg").generate("public-id-of-image");
> 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.
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'
Hello,
cloudinary.url().version().secure(true).format("jpg").generate("public-id-of-image");
What would this look like for jQuery or JS version?
Thank you,
Mike
Hi Mike,
Here is the equivalent call in jQuery:
$.cloudinary.imageTag("sample", { version: 12345678, secure: true, format: 'jpg'});That would generate the following URL:
https://res.cloudinary.com/<cloud_name>/image/upload/v12345678/sample.jpg
Hope this helps!
Hi Marissa Masangcay,
How will the below be in python?
$.cloudinary.imageTag("sample", { version: 12345678, secure: true, format: 'jpg'});Hi Arun,
If you would like to only generate the delivery URL in Python you should use the following:
Alternatively, if you prefer generating the entire HTML Image tag, you can use the below example:
Hi Raz,
As per your advise i used the below command but the link i got is not available.
https://res.cloudinary.com/dbzzesx66/image/upload/v12345678//content/abc_cropped_2.jpg.jpg
Kindly help me
I actually want one url that can be updated with different images, yet the url has to be same.
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.