Why the metadata needs your images’ address
Each NFT’s metadata file has an image field that tells marketplaces where its picture is. Export from Puffles Studio before anything is hosted, and that field holds a placeholder:
"image": "ipfs://REPLACE_WITH_IMAGES_CID/1.png"Nothing can show a picture from that. Once your images are online, the placeholder is swapped for the real folder address, and each file keeps its own file name on the end (what the other fields mean).
The order to do it in
- Build the collection.
- Upload the images/ folder to your host, as one folder.
- Copy the folder’s address. On IPFS, that is the folder’s CID, the code that identifies it.
- Put the address into the metadata in the studio, and download the metadata again.
- Upload the json/ folder and point your contract or drop at it.
Which address to use: ipfs://, https:// or ar://
| Form | Example | Notes |
|---|---|---|
| ipfs:// | ipfs://bafybeigdy… | IPFS calls these addresses “the canonical representation” for its content |
| A bare CID | bafybeigdy… | The studio adds ipfs:// for you |
| https:// | https://example.com/images | Your own server, or an IPFS gateway. No “?” part |
| ar:// | ar://<transaction id> | Arweave. OpenSea reads ar:// addresses (OpenSea) |
IPFS’s own guide recommends ipfs:// inside metadata, because a gateway link “can fail if the gateway operator goes offline” (IPFS). Always give the folder, never one picture: an address ending in .png is refused. The studio writes <address>/<file name> into each NFT’s image field, as in ipfs://<CID>/1.png.
Three ways to set it in Puffles Studio
Before you build, or any time: the Metadata tab
Fill in “Images folder address” and it goes into every file you export. You can also set it on a project you already built: enter the address in the Metadata tab and press Download metadata. You get a metadata ZIP (json/, _metadata.json, rarity.csv and opensea_Metadata.csv) with the address in place. This matches your images only while the seed and settings are unchanged, because the metadata is made from the same plan.
After a build on this device: My collections
In My collections, choose “Update metadata in a finished export” and open the finished ZIP (up to 512 MB). Enter the hosted images folder address and press Download metadata. You get <name>-updated-metadata.zip, holding json/, _metadata.json, opensea_Metadata.csv and rarity.csv. The images aren’t touched or made again.
After a cloud build: the build page
On the cloud build’s page, paste the hosted images folder address and press Update. Every metadata file is rewritten, and “Download the updated details” gives you <name>-updated-metadata.zip.
Keep the seed and settings unchanged
Your images were made from one plan. Change the seed, a weight, a rule or the layer order and download metadata again, and the new files describe a different collection that won’t match your pictures. Updating a finished export avoids this: it only swaps the address.
If you change one image, the address changes
An IPFS address is made from the content itself: “Any difference in the content will produce a different CID” (IPFS). Replace one picture and the folder gets a new CID, so upload the folder again and set the new address.
Keeping files online (pinning)
Copies of your files on IPFS “are temporary and will eventually be deleted unless the user decides to pin the data” (IPFS). Pinning tells IPFS to keep them. Puffles Studio doesn’t host or pin anything, so use a pinning service or your own IPFS node, and keep your own copy. Hosting and pinning fees are separate from Puffles.
Questions people ask
Do I have to rebuild my images to change the address?
No. Open the finished ZIP in My collections (“Update metadata in a finished export”), or use the build page after a cloud build. Only the metadata is rewritten.
ipfs:// or a gateway https:// link?
IPFS recommends ipfs:// inside metadata, because a gateway link fails if the gateway goes offline. The studio accepts both.
Can I use Arweave?
Yes. Enter the folder’s ar:// address. OpenSea’s docs list ar:// as a supported address.
Why does it say REPLACE_WITH_IMAGES_CID?
It’s the placeholder the studio writes until you set your images folder address.
Does Puffles upload to IPFS for me?
No. Puffles doesn’t host or pin files. A cloud build keeps your files for a few days so you can download them; it doesn’t publish them.