Native token balances now live Get started

Article: How SimpleHash makes handling NFT media easier

Published on: 5/15/2023

How SimpleHash makes handling NFT media easier

Most NFTs are comprised of three main types of information – the on-chain ownership data, the off-chain metadata, and the media.

Since NFTs are so strongly associated with imagery or visual details, getting the details right on handling NFT media is extremely important for delivering a great end-user experience. But doing so isn’t always easy – NFT media can come in many different formats and standards, and delivering the content reliably and efficiently can also be a challenge, especially for wallet or minting platform applications that may feature a large number of tokens at once.

In this post, we walk through some of the challenges in working with NFT media, and how SimpleHash solves these challenges.


Different NFT media formats

NFTs have historically been strongly associated with PFP collections – those containing a defined number of tokens (often 10,000) featuring variations of the same base image. These are often PNG or JPEG files, and usually straightforward to render. An increasing number of NFT collections make use of different media formats however – including SVGs, videos, 3D models and audio files. As NFTs are picked up for different use cases, an increasing number are multi-modal, and may incorporate many different file formats, or change dynamically, depending on the state of the metadata.

SVGs in particular can be challenging to render within certain frameworks, particularly on mobile devices. They also can pose security risks, with malicious code sometimes being placed within the SVG itself. SimpleHash aids with the handling of SVGs, by converting all SVGs files into PNGs, which render more consistently on all devices. These conversions are done automatically, and can be found within the previews field of the NFT response bodies obtained from the SimpleHash API.

NFTs with videos and 3D models pose a different set of challenges, in that many provide incorrect MIME types, or are provided in a non-standard format. This makes it difficult for the client application of the NFT content to display it correctly, or at all. SimpleHash makes this easier by checking the file format of every media file ingested by our indexer, and passing along the correct format if it is found to be different, based on an analysis of the file bytes. This makes media rendering more predictable and reduces the number of extra tasks or scripts an NFT application developer has to put in place.

SimpleHash also provides still-frame thumbnail images of video and 3D models files, providing an additional option for displaying previews, smaller-sizes, or more compatible versions of these types of NFT media.


Detailed media information and metadata

Providing access to the media is a necessary, but not always sufficient part of rendering NFTs well. For many applications, knowing the aspect ratio of the image, the predominant color, presenting a loading image, or knowing the size, duration and encoding of the file can be crucial to the front-end presentation. For example, a gallery product may desire to include a blurhash to improve visual appearance while all media files load. Or the layout of a mobile application may depend on knowing the aspect ratio of the media file.

The SimpleHash API provides all of this information, directly within the NFT response bodies. Each response includes the fields image_properties and video_properties, which are populated depending on the original media file in question. They include the width and height of the media files, their size in bytes, the mime_type, the encoding, and the duration (for videos). Within the previews field, we also include info on the predominant color of the media (helpful for creating pleasant looking NFT UIs), and the blurhash of the image – the blurhash is a simple encoding of the image that can be rendered to provide a blurred preview of the media before it loads, instead of a blank container.


Fast loading media and dynamic previews

Speed is crucial to any end user application, and a large part of that is the rendering speed for the NFT media. Reliability is another key consideration – it’s not a great experience if the media doesn’t load consistently, or if there are frequent timeouts.

Working with the media on many NFT collections faces both challenges. Many original NFT media files are saved in large, unoptimized files (often to preserve the quality and detail of the original artwork). The challenge comes when downloading these files, especially for many at once. As an example, it’s likely undesirable for a wallet application to present dozens of 5MB+ images for the NFTs in a user’s wallet at once, especially if the user has many NFTs, or if they are being displayed in a small format where the extra resolution would be wasted. This is especially true for videos, which can be hundreds of megabytes or more, which are especially problematic for mobile form-factors where bandwidth may be constrained.

The original media for many NFT collections are based on decentralized systems, such as IPFS, or Arweave. Many of these links must be accessed via a gateway, and encounter challenges with timeouts or slow loading times. NFT media files not located on decentralized stores can still encounter these challenges, especially if they are hosted on a service that is unoptimized or cannot provide high bandwidth. Loading media directly from these sources can therefore result in an inconsistent end user experience.

SimpleHash helps solve both the speed and reliability challenges via our dynamic CDN preview service. Our indexer caches every single media file we ingest, and serves them up via our CDN, for faster and more reliable access. These versions are provided inline via the NFT response bodies from the API, depending on the use case.

  • image_url / video_url / audio_url / model_url – the unaltered original media file, cached to the SimpleHash media CDN. These links are useful for when a developer requires the original version of the media, but to access it from a fast loading and consistent source.

  • previews – this field contains the dynamic preview versions of the NFT media – these are also saved to the SimpleHash CDN, but are resized, to allow for even faster loading, where the full-size versions are not required. By default, the API provides a set of convenient sizes: (Small – up to a 250px max dimension, Medium – up to a 500px max dimension, Large – up to a 1000px max dimension, OpenGraph – sized to render well for OpenGraph preview applications (e.g., Twitter or other social media links))
  • These previews can be resized to other dimensions on the fly however, but changing the s parameter at the end of the link (e.g., s=768)
  • The preview field also includes the blurhash and predominant color fields

The preview versions offer further benefits for SVG, video, and 3D model media – for these types of media, the previews will be rendered as still frame PNGs, helping with compatibility, and loading speed (as the preview thumbnail versions will generally load much faster).

Utilizing the media from the SimpleHash CDN offers the further advantages of much lower risk of timeouts, and reduced bandwidth usage when using the previews. It also avoids having to utilize a gateway service for accessing media from IPFS or other similar sources.

For most NFT media files, the SimpleHash indexer ingests and caches the file on the first try. In some situations, however, the original media source might be throwing an error, timing out, or be otherwise inaccessible. To overcome this, the indexer media engine employs an intelligent backoff schedule, retrying the media at later points in time, or via different proxies, until it can be found. Once the media is retrieved and cached on the SimpleHash CDN, and made available via the dynamic previews, it will be stored for any app developer to use. This process reduces complexity for client NFT applications, and is one less error checking mode that needs to be implemented.


SimpleHash makes dealing with NFT media easier 

At SimpleHash we spend a lot of time getting the details around NFT media handling right, so that crypto and developers of NFT apps don’t have to. Media is at the core of what makes an NFT an NFT, and we’re continually working on improvements and quality of life enhancements to make creating the best NFT experiences as easy as possible. If you’re building an application that makes heavy use of NFT media, or has bespoke requirements, please don’t hesitate to get in touch at

Getting token & NFT data is hard.

SimpleHash makes it easy.

Trusted by hundreds of web3 leaders:

Coinbase logo
Floor logo
Ledger logo
Brave logo
Rarible logo
Rainbow logo
Phantom logo
Manifold logo
Venly logo
Exodus logo
Zerion logo
Nansen logo
Dappradar logo
Dust Labs logo
Unstoppable Domains logo
Mask logo
Crossmint logo
Tiplink logo