Media proxy (alfa)

The concept of media proxy deals with use cases when you don’t want to handle image uploads or storage but head straight to optimizing your images and their delivery.

The workflow is focused on using proxy that fetches your content, optimizes and delivers it to your users via Uploadcare CDN. There is more to it; you can also apply any Image Transformations to further optimize your media.

Media Proxy is the fastest way to integrate Uploadcare into your product without modifying your code or manually migrating any files.

Setting Up

Here are the three simple steps it takes to set up Media Proxy:

Step 1. Get a Proxy Endpoint

By default, we create a proxy endpoint for every project. You can find it in the Whitelist section of project settings. If you want to use your subdomain name like instead of the auto-generated one, drop us a line.

Step 2. Provide a List of Allowed Domains

We also require you to provide a list of domain names you’d want the proxy to fetch files from. Those are called “allowed domains.” You can add them in the same section.

That’s it, you can now start using Media Proxy.

Using Media Proxy

Here are the steps we recommend taking to start off with the Media Proxy.

Step 1. Check How Everything Works

Add your Media Proxy prefix to a media URL you want to fetch, an image for example: + =

If you have done everything right, image.jpg is now delivered via Uploadcare CDN.

Step 2. Play With Image Transformations

Apply some transformations to your image by adding one of their respective URL Directives between the prefix and media URL. We’d go with resizing an image to 500 pixels in width with the resize operation by adding -/preview/-/resize/500x/:

The resized version of image.jpg is now delivered by Uploadcare CDN.

Step 3. Add Prefixes to Your Media

Iterate through your media assets and add your Media Proxy prefix to every URL, apply operations when needed. You can also optimize your workflow and free up some storage space, i.e., if you got multiple versions of images for adaptive layouts. Those can now be made on-the-fly by crafting proper URLs using our Image Transformations directives.

1260 pixels in width:

760 pixels in width:

512 pixels in width:

You can find more on implementing Responsive Images with Uploadcare on our blog.

Step 4. Run Some Tests

Measure your load time and traffic improvement by comparing those for your original files and their optimized versions. For local tests, you can use common stuff like chrome-devtools. With image content, consider playing with the quality transformation for better results.

Note, there’s no performance improvement when using any Media Proxy URL for the first time. Fetching happens first, and starting with the second use of the URL, your files are delivered from our CDN.

Media Proxy Use Cases

We crafted a collection of the most relevant Media Proxy use cases. In general, it helps optimizing your assets thus improving load times and cutting traffic spendings.

Improve Load Times

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

When handling media, 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.
  • quality, adjust image quality.
  • resize, adjust image size.

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

Implement Responsive Images

Once your files get fetched by the Media Proxy, there is just one step to building responsive designs. With images, it is about generating their different versions to use with your srcset or the <picture> element. Image Transformations would be the feature to use here.

We published a dedicated article on using Image Transformations that covers all the techniques to get responsive.

Cut Traffic Spendings

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

The framework here is quite the same as in the load times section: you control media formats, quality levels, and dimensions thus getting smaller files without a loss in visual quality.

Migrate To The Cloud

It might happen you are already using a File API or cloud storage for your assets. In both cases, it is relatively easy to migrate: you, set up Media Proxy, make a list of your asset URLs, and replace those with their optimized versions.

Your existing media assets may already be transformed on-the-fly with a File API. To migrate those, you might also need to look through the Image Transformations we support and how to use them with Media Proxy. That helps determine operation alternatives and their syntax.

Seamlessly Integrate Uploadcare

The simplest way to integrate file APIs is doing it from scratch, i.e., when developing a new product or scaling an existing one. That’s not always the case. When you have already got a bunch of assets, use Media Proxy to fetch those to Uploadcare and optimize their delivery on autopilot. This can be done in four simple steps:

  • Set up the Media Proxy.
  • Iterate through all of your assets and parse their URLs.
  • Fetch those assets via Media Proxy to your Uploadcare project.
  • Change your asset URLs to their optimized versions: add prefixes.

Assess Your Performance

Before signing up or migrating, you want to measure how Uploadcare can improve your system’s performance. Our advice, in this case, is using Uploadcare only for certain areas of your web or mobile app and then comparing how they perform before and after integrating with Uploadcare:

  • Pick an area of your web or mobile app that you monitor: understand conversions and average load times.
  • Set up Media Proxy to work with your Uploadcare account.
  • Iterate through your assets related to that preferred area and replace URLs with their optimized versions: add prefixes.
  • Apply transformations to further optimize your media assets where applicable.
  • Run tests, collect statistics, and compare how the tested part of your web or mobile app performs after implementing optimizations.

Possible Errors

Here is the list of errors you might get when using Media Proxy:

[HTTP 400] Domain <> is not registered

You did not register a Media Proxy domain for your sites by dropping us a line at

[HTTP 400] Domain <> 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. Perform another try sometime later or contact us.

Other errors

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