Hedera NFT Metadata, HIP-412 and IPFS Explained

NFT metadata connects the token you own with the item a wallet displays. For a typical Hedera NFT, there are three pieces: a small metadata value on the ledger, a JSON description and the media files referenced by that description.

Understanding those pieces helps you fix a missing image and prepare a collection that other applications can read.

The three layers

The NFT's on-ledger metadata often contains a URI pointing to a JSON file. That JSON describes the NFT and points to its image or other media. The image is a separate file.

Changing a draft in a creator tool does not automatically change the NFT already recorded on Hedera. Likewise, opening a gateway URL does not mean the file is stored inside the token.

NFT metadata bytes
JSON
Media

What HIP-412 provides

HIP-412 describes a shared metadata format for Hedera NFTs. It gives creators and applications common names for fields such as the NFT's name, image and media type. A description and attributes add useful context.

This simplified example shows the shape. Replace the bracketed values with real content addresses before using it:

{
  "name": "Night Window #1",
  "description": "A study of a lit window after midnight.",
  "image": "ipfs://<image-cid>",
  "type": "image/png",
  "attributes": [
    { "trait_type": "Window", "value": "Violet" }
  ]
}

Use the maintained HIP-412 specification for required fields and richer media. Royalty settings and maximum supply belong to the token's network configuration; putting numbers into this JSON does not configure them on Hedera.

Content addresses and gateways

An IPFS content identifier, or CID, identifies content under its encoding and import settings. An ipfs:// address names that content. An HTTP gateway is one way a browser retrieves it.

If a gateway stops responding, another gateway can sometimes retrieve the same content. That does not help if no provider still stores and serves the files. Keep pinning and source backups as part of maintaining the collection.

Check the metadata before minting

Open the JSON and the media it references. Check the name, media type, filename case and traits. For a collection, inspect entries from several parts of the set rather than only the first file.

In DreamForge, verify the draft and its pinned preview before minting. After a successful mint, check the actual serial in a wallet or on SentX. This catches differences between the draft and what applications now retrieve.

DreamForge pinning confirmation showing file details and a quote — Review the current quote for the files in this operation.

If the artwork is missing

Start with the token ID and serial. Check the NFT metadata value, then the JSON it points to, then the media address. This order tells you which layer is failing.

Do not remint an existing NFT just to refresh a missing image. Read metadata updates and check the token's available authority first.

Prepare your first NFT in DreamForge.