Store and mint NFTs using custom metadata

The JavaScript client library provides three methods that you can use to store arbitrary files for your NFT assets and metadata.

The storeBlob method accepts a single Blob or File object and returns the CID of the uploaded file. Note that the original filename and content type information will not be preserved, and the CID returned by storeBlob will point directly to the file data.

To preserve filenames, or to upload multiple related files at once, use the storeDirectory method. storeDirectory takes multiple File objects and wraps them with an IPFS directory listing. This allows you to link to the files using human-readable names as the "path" component of your IPFS URIs or gateway links.

It's important to note that storeDirectory returns the CID of the directory listing, and you'll need to append the filename to the CID to construct links to the files themselves.

For example, storing an image named pinpie.jpg using storeDirectory might return the CID bafybeiajdopsmspomlrpaohtzo5sdnpknbolqjpde6huzrsejqmvijrcea. If you view this CID on an HTTP gateway, you should see a directory listing page with a link to the file pinpie.jpg.

To link to the image, you'll need to add /pinpie.jpg to the CID to create a valid IPFS URI:

ipfs://bafybeiajdopsmspomlrpaohtzo5sdnpknbolqjpde6huzrsejqmvijrcea/pinpie.jpg

The final method for storing arbitrary data is storeCar, which stores data that has been packaged into the IPFS Content Archive format. This method gives you precise control over how the IPFS object graph is structured and may be a good fit if you already have data in IPFS. See the CAR file guide to learn how to work with CARs and prepare them for upload.

The HTTP API provides a /upload endpoint that accepts one or more files and stores them with NFT.Storage.

Single file#

To upload a single file, send a POST request to /upload with the binary file data as the request body. The Content-Type header should be set to a type that's appropriate for the content, for example, image/jpeg.

You should get a response similar to this one:

{
  "ok": true,
  "value": {
    "cid": "bafkreidivzimqfqtoqxkrpge6bjyhlvxqs3rhe73owtmdulaxr5do5in7u",
    "size": 132614,
    "created": "2021-03-12T17:03:07.787Z",
    "type": "image/jpeg",
    "scope": "default",
    "pin": {
      "cid": "bafkreidivzimqfqtoqxkrpge6bjyhlvxqs3rhe73owtmdulaxr5do5in7u",
      "name": "pin name",
      "meta": {},
      "status": "queued",
      "created": "2021-03-12T17:03:07.787Z",
      "size": 132614
    },
    "files": [
      {
        "name": "logo.jpg",
        "type": "image/jpeg"
      }
    ],
    "deals": [
      {
        "batchRootCid": "bafkreidivzimqfqtoqxkrpge6bjyhlvxqs3rhe73owtmdulaxr5do5in7u",
        "lastChange": "2021-03-18T11:46:50.000Z",
        "miner": "f05678",
        "network": "nerpanet",
        "pieceCid": "bafkreidivzimqfqtoqxkrpge6bjyhlvxqs3rhe73owtmdulaxr5do5in7u",
        "status": "queued",
        "statusText": "miner rejected my data",
        "chainDealID": 138,
        "dealActivation": "2021-03-18T11:46:50.000Z",
        "dealExpiration": "2021-03-18T11:46:50.000Z"
      }
    ]
  }
}

Multiple files#

To upload multiple files, send a POST request to /upload containing multi-part FormData in the request body. The Content-Type header must be set to multipart/form-data.

Each "part" of the multi-part form data should include a Content-Disposition header, which specifies the name of the form field (always "file"), and the filename. The part header should also include a Content-Type header with a value appropriate for the data being uploaded.

Here's an example:

------WebKitFormBoundary5peilISl2YOOweQy
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png

<data>
------WebKitFormBoundary5peilISl2YOOweQy--

The ------WebKitFormBoundary5peilISl2YOOweQy tokens in the example above set the boundary of each "part" within the form data. In most cases, this will be set automatically by whatever request library or API is preparing the form data body. If you're preparing multi-part requests manually, see RFC7578.

CAR files#

The /upload endpoint has some special support for IPFS Content Archives (CARs) that can be used to upload files larger than the 100 MiB single-request limit.

Uploading CAR files works just like uploading a single file. Send a POST request to /upload, with the Content-Type header set to application/car and the binary file data as the request body.

To upload files larger than 100 MiB, you can pack them into a CAR file and split the CAR into chunks, uploading each chunk in a separate HTTP request. See the CAR file guide to learn more.