NFT Metadata Explained: What It Is, How It Works & How to Upload to Pinata
Every NFT has two parts: the image people see, and the metadata that describes it. Get the metadata wrong and your collection won't display correctly on any marketplace. Here's exactly how it works — and how to set it up properly using Pinata and TheMintLab.
01 — What Is NFT Metadata?
Metadata is a JSON file that lives alongside your NFT image. Every token in your collection has its own metadata file. Marketplaces like OpenSea, Magic Eden, and Blur read this file to display your NFT's name, description, image, and traits.
Without correct metadata, your NFT will appear as a blank token with no image and no attributes — which makes it unsellable on any major marketplace.
A standard metadata file looks like this:
Example 1.json:
{ "name": "MintLab #1", "description": "A generative NFT collection.", "image": "ipfs://YOUR_CID/1.png", "attributes": [ { "trait_type": "Background", "value": "Blue" }, { "trait_type": "Eyes", "value": "Laser" } ] }
Each token gets its own numbered file: 1.json, 2.json, 3.json and so on. The image field points to the corresponding image on IPFS.
02 — Generate Your Metadata Automatically
Writing hundreds or thousands of JSON files by hand is not feasible. TheMintLab's metadata tool generates all your metadata files automatically — correctly formatted and ready to upload.
Generate Your NFT Metadata in Minutes
Upload your collection details and get perfectly formatted JSON metadata files — free, no account needed.
Open Metadata Tool →03 — Upload Your Images to Pinata
Pinata is the most popular IPFS pinning service for NFT projects. It stores your images permanently on IPFS and gives you a CID to reference in your metadata.
Step-by-step: uploading to Pinata
- Go to pinata.cloud and create a free account
- Click Upload → Folder and select your images folder (containing 1.png, 2.png, etc.)
- Give the folder a name (e.g. "my-collection-images") and click Upload
- Once uploaded, Pinata shows you a CID — a long string starting with "Qm" or "bafy"
- Copy your CID — you'll need it in the next step
Free tier: Pinata's free plan includes 1GB of storage — enough for most small collections. For 10,000 images you may need their paid plan or NFT.Storage as a free alternative.
04 — Get Your CID and Update Your Metadata
Once your images are on Pinata, you have a CID. Now you need to update your metadata files so the image field in each JSON points to the correct IPFS location.
The format is: ipfs://YOUR_CID/1.png — where YOUR_CID is the folder CID from Pinata, and 1.png matches the token number.
TheMintLab's metadata tool lets you enter your CID and automatically generates all metadata files with the correct image paths already filled in — no manual editing required.
05 — Upload Your Metadata Folder to Pinata
Once your JSON files have the correct image paths, upload the entire metadata folder to Pinata the same way you uploaded the images:
- Click Upload → Folder in Pinata
- Select your metadata folder (containing 1.json, 2.json, etc.)
- Copy the new CID — this is your base URI
- Your base URI will be: ipfs://METADATA_CID/
- Enter this base URI into your smart contract when you deploy
Check it works: After uploading, visit https://gateway.pinata.cloud/ipfs/YOUR_CID/1.json in your browser. You should see your first token's metadata displayed correctly.
You're Ready to Mint
With your images and metadata both on IPFS and your base URI in hand, you have everything you need to deploy a smart contract and mint your collection. Start with the TheMintLab metadata tool to get your JSON files sorted first.
Frequently Asked Questions
What is NFT metadata?
NFT metadata is a JSON file attached to each token that describes it — including its name, description, image URL, and a list of traits/attributes. Marketplaces like OpenSea read this file to display your NFT correctly.
What is a CID in IPFS?
A CID (Content Identifier) is a unique hash that IPFS generates when you upload a file. It's how your NFT metadata and images are addressed on the decentralised web — permanent and tamper-proof.
Do I need to update my metadata after uploading to Pinata?
Yes. Once you have your image CID from Pinata, you need to update the image field in each JSON metadata file to point to ipfs://YOUR_CID/1.png before uploading the metadata folder.
What tool can I use to generate NFT metadata automatically?
TheMintLab's metadata tool at themintlab.xyz/metadata-tool generates compliant JSON metadata files automatically from your collection details — no coding needed.
Is IPFS storage permanent?
IPFS itself is permanent as long as the file is pinned. Pinata keeps your files pinned so they stay accessible. Without pinning, files can disappear from the network over time.