Guides

How to host Deep Zoom images without a server

Upload the image to ZoomHub, which tiles and hosts it, then fetch the asset from the API when your page loads and hand its DZI URL to OpenSeadragon. There are no tiles to generate or store, no server to run, and reading an image needs no API key.

Try it: this image, in your own viewer

Bosch’s triptych, crowded with tiny figures, giant fruit and fantastical creatures
The image the code below opens, shown here in ZoomHub’s own viewer. Paste the code into a page to see it in OpenSeadragon.
HTML
<div id="viewer" style="height: 480px"></div>
<script src="https://cdn.jsdelivr.net/npm/openseadragon@6.0.2/build/openseadragon/openseadragon.min.js"></script>
<script type="module">
  const response = await fetch("https://api.zoomhub.net/v2/assets/cHzay7iRJVY")
  const asset = await response.json()

  OpenSeadragon({
    id: "viewer",
    prefixUrl: "https://cdn.jsdelivr.net/npm/openseadragon@6.0.2/build/openseadragon/images/",
    tileSources: asset.image.dzi.url,
  })
</script>

Step by step

  1. Upload your image

    On the ZoomHub homepage, choose the file or paste a link to it. JPEG, PNG, TIFF, WebP, GIF or PDF all work.

  2. Confirm your email

    Enter your email address and open the link I send you. If you’re signed in, there’s nothing to confirm.

  3. Find the image’s ID

    It’s the last part of the image’s address.

  4. Fetch the asset when your page loads

    Ask the API for the asset each time, as the code above does, and read its DZI URL at image.dzi.url. Don’t save that URL or write it into your page: it can change, for instance when the image’s owner protects it.

The facts

API key
Reading a Public or Unlisted image needs none, and browsers can call the API from any origin, so no key ends up in your page. See the API reference.
Plans
This read works for images on every plan. Free is for personal use; commercial use needs a paid plan. On Free, a viewer of your own must show “Powered by ZoomHub” with a link to zoomhub.net, as ZoomHub’s viewer does; a paid plan removes it.
Check first
While an image processes, its type is null and there’s no DZI to open. Wait for a status of succeeded.
File size
Up to 1 GB per file on Free, and 5 GB on paid plans.
Formats
JPEG, PNG, TIFF, WebP or GIF.

Questions

Why fetch the asset every time?

The DZI URL isn’t a permanent address, but the image’s ID doesn’t change. Fetching the asset gives you the URL that’s current, so your page keeps working when the tiles move.

Does this work for password-protected images?

Not from a public page. Reading a Protected image takes the owner’s API key, which must never go into a browser. Use ZoomHub’s own embed for those: it asks visitors for the password.

Do I need OpenSeadragon at all?

Not unless you want your own viewer. ZoomHub’s embed is one line of HTML, with no library to load, and it has options for its size, fit and minimap.

Can I upload from code too?

Yes, on the Business plan: with an API key you create assets from a URL or an upload, and set titles and reference IDs.