Uploadcare Proxy

Uploadcare delivers your files with a powerful CDN. It implies that you need to upload files to Uploadcare storage first. If you want to use our CDN without explicitly uploading files to Uploadcare, this is the feature you want to use. Proxy allows you to integrate Uploadcare into your solution with only minor URL modifications:

https://yoursite.ucr.io/ + https://yoursite.com/assets/image.jpg =

Proxy will upload files to your Uploadcare storage as soon as they’re requested. It will also allow you to use Uploadcare CDN features.

Primarily, Proxy is used to deliver images along with image transformations. You can deliver other files as well. Your original file URLs will still work.

Note: Try out Adaptive Delivery which adapts images to any device automatically with a simple setup. Use Proxy for a more manual approach.

Setting Up

Open your Uploadcare project's Dashboard and select Delivery from the main menu on the left. Click Connect for Proxy.

Step 1. Provide a List of Allowed Domains

Specify the domain names that host your files. The Proxy will recognize these domains and deliver files successfully. You can add one or more domains in the Proxy dialog window.

Step 2. Custom Proxy Endpoint (optional)

By default, Uploadcare creates a proxy endpoint for every project automatically: PUBLIC_KEY.ucr.io (e.g., 88a247b663ba80c3bf6f.ucr.io).

As you can see, a default subdomain for the endpoint is your project's Public key. All links start with this URL, so you can change it to something readable. Custom endpoint examples:

  • CNAME or subdomain endpoint will look like: mydomain.ucr.io
  • A record or domain endpoint will look like: cdn.mydomain.com

Using Proxy

Here's how to use Proxy after it's set up.

Step 1. Add Proxy prefix

Add the Proxy prefix that contains your Endpoint to a file URL on the allowed domain:

https://yoursite.ucr.io/ + https://yoursite.com/assets/image.jpg =

After that, image.jpg will be delivered via Uploadcare CDN. The original file will remain at its original place, so that older references will work as well.

Now you can add prefixes to all images using your IDE or text editing tool. Apply CDN operations when needed.

Step 2. Apply image transformations

You can apply image transformations by adding one of the respective URL directives between the prefix and media URL.

This CDN operation will resize image.jpg to 500 px in width by adding -/preview/-/resize/500x/:


As a result, image.jpg will be resized and delivered with Uploadcare CDN.

You can also optimize your responsive image handling workflow and free up some storage space by deleting image versions in different sizes for adaptive layouts. Uploadcare resizes images on the fly and you don't have to save all versions beforehand. Here's how to generate multires images:

1260 pixels in width:

760 pixels in width:

512 pixels in width:

Find out more on implementing responsive images down below.

Possible Errors

Here's a list of errors you might get when using Proxy:

[HTTP 400] Domain <yoursite.com> is not registered

You did not register a Proxy domain for your sites by dropping us a line at help@uploadcare.com.

[HTTP 400] Domain <yoursite.com> is not allowed

You tried fetching a file from a domain that was not allowed. Check settings or contact us to add the domain as allowed for your account.

[HTTP 400] Failed to parse file URL

Your prefix was added to an invalid URL. Consider checking that URL.

[HTTP 404]

You tried fetching an unreachable file. Consider checking its URL.

[HTTP 502] 'is_ready' timeout

A problem occurred when trying to upload a file to our storage. Try again later and if it didn't help you always can contact us.

Other errors

Proxy uses the from_url method, so you can also get general errors related to the Upload API or specific to the from_url method.

Proxy Use Cases

We picked a collection of the most popular Proxy use cases. These cases are about optimizing traffic, improving load time, and handling your assets the way you need.

Implement Responsive Images

After you set up delivery with Proxy, there's just one step to build a responsive design. Responsive images require that you prepare images in different sizes and later list them in the srcset attribute or the <picture> element.

Check out our blog article on Image Transformations that covers responsive techniques.

Improve Load Time

Uploadcare Proxy fetches your assets and delivers them via Uploadcare CDN. That alone improves load time of your assets because they get served from a CDN node best for your client’s location.

When handling media, Proxy provides further load time improvement by letting you cut file sizes at no visual quality loss. With images, that can be done via our Image Transformations feature.

Specifically, take a look at the following on-the-fly operations:

  • format, convert images to WebP, PNG or JPEG. It's recommended to use format/auto
  • quality, adjust image quality.
  • resize, adjust image size.

This set of tools can help accelerate your images up to 9x.

You can compare page load time and traffic optimization with Uploadcare CDN and without. Use tools like Chrome DevTools for local tests. Play around with the image quality and find a sweet spot for the best visual traffic compression results.

Note that the first request for each media file over Proxy URL will copy it to Uploadcare CDN. Therefore, there won't be a performance improvement yet. However, once it gets copied to our servers, all subsequent requests will fetch the file from the closest CDN node.

Cut Traffic Costs

While accelerating your media improves your conversions, using less bandwidth cuts your traffic costs.

The workflow here is quite the same as in the load time section: you control media formats, quality levels, and dimensions. It helps you get smaller files without any visual quality loss.

Migrate to the Cloud

A possible case is that you already use a File API or cloud storage for your assets. In both cases, it is easy to migrate. Set up Proxy, make a list of your asset URLs, and replace them.

Your existing media assets may be transformed on-the-fly with the File API. Read more on Image Transformations here in docs. Learn how to use them with Proxy.

Proxy billing

This feature is free and available across all plans. It is important to note that proxy uses your project upload units and storage limits since files are fetched and saved first before they are available on Uploadcare's CDN.