How AIOZ Pin Works: Pinning, Gateways, and NFT Tools

AIOZ Pin works through three components on the AIOZ DePIN network. Files Pinning keeps your files on IPFS, NFT Management pins an NFT's asset and metadata in one request, and Premium Gateways serve that content over HTTP. You pay for storage and bandwidth from a wallet funded with AIOZ tokens.

TL;DR:

• AIOZ Pin has three documented parts: Files Pinning, NFT Management, and Premium Gateways, all running on AIOZ DePIN.
• Storage costs $20 per TB per month and bandwidth $20 per TB, billed daily. The first 40,000 pinned files are free.
• You can reach it through the REST API, the Node.js SDK, a pinning CLI, or the standard IPFS Pinning Service API.

Updated Oct 19, 2026: new architecture diagram, gateway limits and billing rechecked against the docs, an unsourced "storage proofs" claim removed, and a closing upload example.

What are the three components of AIOZ Pin?

Our docs describe AIOZ Pin as "the top layer of the AIOZ DePIN." Everything you do with it lands in one of three components. The diagram shows how a request from your app reaches each one, and what sits underneath.

Under all three, AIOZ DePIN adds smart caching of frequently accessed content and smart routing that sends each request to the nearest available node. The docs also list built-in CDN capabilities. Those two features are why a popular file loads faster than a cold one.

Files Pinning: how persistence works

An IPFS node runs garbage collection from time to time and deletes any block that nobody marked as important. Pinning is that mark. When you pin a file on AIOZ Pin, our nodes keep its blocks, so the CID keeps resolving whether or not anyone requested it this week.

You have two ways in. Upload a file or folder with POST /api/pinning and get a CID back. Or, if the content already exists on IPFS, send its CID to POST /api/pinning/pinByHash and we fetch the blocks from the network. The second route is handy when you move from another provider, because nothing needs uploading again.

File count has its own small charge. The first 40,000 pinned files are free, and each extra 1,000 costs $0.10. So a project with 100,000 small files pays $6 a month for the count, on top of storage. Our free pins explainer works through more examples.

The docs describe the caching and routing layer, but they don't publish an uptime SLA or a replica count per file.

How do AIOZ Pin gateways work?

A gateway turns a CID into an ordinary HTTPS URL, so a browser can load IPFS content without running a node. AIOZ Pin gives you two kinds, and the limits differ a lot.

• Public gateway (public.aiozpin.network): open to anyone, no account needed. Each CID is limited to 15 requests per minute across all users, and each IP to 200 per minute. The docs call it a testing tool, not a production one.
• Premium gateway (your own subdomain): no predefined rate limit, served through 200+ edge caching locations. Free plan users get a limited version that serves single files such as images, video, and audio, but not HTML or scripts.

If your wallet runs out while a premium gateway is on, the gateway switches off. Your files stay pinned and still load through the public gateway. Our dedicated gateways guide covers setup, and how an IPFS gateway resolves a request explains the general mechanics.

Gateways also handle images. Add parameters such as img-width, img-fit, or img-quality to a gateway URL and you get a resized copy, with no second upload. The image resizing guide lists every parameter.

NFT Management: what pinNft does

Through the API, you send the asset file and the metadata JSON in one multipart POST /api/nft/ request. The response returns an asset_cid and a metadata_cid, and the metadata CID is what goes into your token's URI.

In the Node.js SDK (@aioznetwork/aioz-pin-sdk, version 1.0.1), the same call is pinNft. Pinning both pieces at once means you can't end up with metadata that points at an asset nobody pinned. The SDK also ships pinFilesToIPFS and pinFolderToIPFS for general files, plus pinByHash for content that already has a CID. The quick start page spells the first one pinFileToIPFS, but the published package uses the plural form.

Content addressing is why this suits NFTs. A CID comes from the file's bytes, so changing one byte gives a different CID. A buyer can check that the metadata a token points to is the metadata that was minted.

How much does AIOZ Pin cost?

We bill storage and bandwidth separately. Storage is $20 per TB per month, divided by the days in the month and charged daily. Bandwidth is $20 per TB, also charged daily. You fund a wallet with AIOZ tokens, and each deposit converts to credit at the AIOZ/USDT rate at the time you send it.

There are no bundled tiers. Pin 50 GB and serve 200 GB in a month, and you pay about $1 for storage plus $4 for bandwidth. The pricing breakdown has more worked numbers, and the AIOZ Pin vs Pinata comparison sets them against a plan-based provider.

Built on open standards

AIOZ Pin implements the IPFS Pinning Service API at https://api.aiozpin.network/api/psa/. That means you can add it to the Kubo CLI as a remote pinning service and pin from your own node. Code written against the standard moves between providers with an endpoint and token swap. Our PSA explainer shows the exact commands.

For scripts, there is also a Go command line tool on the AIOZNetwork GitHub, pinning-service-cli. It covers pinning login --key ... --secret ..., pinning pin --file, pinning list-pins, and pinning unpin. The CLI tutorial walks through it.

How AIOZ Pin handles your first upload

A first upload takes one request. Create an API key in the dashboard, store the key and secret as environment variables, then send the file as multipart form data. This is the example from the AIOZ Pin API reference (not run on this machine):

import fs from 'fs'
import path from 'path'

const BASE = 'https://api.aiozpin.network/api'
const PIN_HEADERS = {
  'pinning_api_key': process.env.AIOZ_PIN_API_KEY!,
  'pinning_secret_key': process.env.AIOZ_PIN_SECRET_KEY!
}

async function pinFile(filePath: string, name?: string) {
  const form = new FormData()
  form.append('file', new Blob([await fs.promises.readFile(filePath)]), path.basename(filePath))
  if (name) form.append('metadata', JSON.stringify({ name }))
  const res = await fetch(`${BASE}/pinning`, { method: 'POST', headers: PIN_HEADERS, body: form })
  return res.json()
}

const result = await pinFile('./image.png', 'my-image')
// result.data.cid    - IPFS CID
// result.data.id     - pin ID

The CID in result.data.cid then loads at https://public.aiozpin.network/ipfs/<CID>, or through your premium gateway. The general API allows 180 requests per minute, and the /users/ and /apiKeys/ routes allow 60.

Next step: follow the AIOZ Pin quick start to create your key and pin a file.

Frequently Asked Questions

What are AIOZ Pin's three main components? Files Pinning, NFT Management, and Premium Gateways, per the AIOZ Pin infrastructure docs. Files Pinning keeps content on IPFS, NFT Management pins an asset and its metadata together, and Premium Gateways serve content without a set rate limit.

Does AIOZ Pin guarantee my files stay online? Pinned files are kept from garbage collection, and the docs describe smart caching and routing across AIOZ DePIN. They don't publish an uptime SLA or a replica count, so plan your own backups for critical data.

What does the NFT Management feature do? It pins an NFT's asset and metadata JSON in one request, through POST /api/nft/ or the SDK's pinNft, and returns a CID for each.

How much does AIOZ Pin cost? Storage is $20 per TB per month and bandwidth $20 per TB, both billed daily. The first 40,000 pinned files are free, then $0.10 per extra 1,000.

Can I switch to another pinning provider without rewriting my code? For core pinning, largely yes, because AIOZ Pin implements the IPFS Pinning Service API. Provider-specific features such as image parameters or the NFT endpoint need their own changes.

What's the difference between the public and premium gateway? The public gateway is free and open but limited to 15 requests per minute per CID and 200 per IP. A premium gateway has no predefined rate limit and is billed by bandwidth.

Related Reading

• What Is IPFS? How the InterPlanetary File System Works - background on the protocol under AIOZ Pin
• Understanding IPFS Pinning Services - what a pinning service does, and what to check before you pick one
• AIOZ Pin Dedicated Gateways - the premium gateway feature in detail
• How to Resize Images on AIOZ Pin Using URL Parameters - every img- parameter, with examples
• AIOZ Pin vs Pinata - how the pricing above compares with the market leader
• AIOZ Pin for Developers - the API, SDK, and CLI side by side

References

• AIOZ Pin Infrastructure documentation
• AIOZ Pin Payment documentation
• AIOZ Pin Limit documentation
• AIOZ Pin Premium Gateways documentation
• AIOZ Pin API full reference (llms-full.txt)
• @aioznetwork/aioz-pin-sdk on npm
• AIOZNetwork pinning-service-cli on GitHub
• IPFS Pinning Service API specification