Register & Monetize Stability Images

In this tutorial, you will learn how to:

Generate an image with Stability AI
Upload your image to Pinata IPFS
Register your image as IP on Story
Attach License Terms to your IP

The Explanation

Let’s say you generate an image using Stability AI. Without adding a proper license to your image, others could use it freely. In this tutorial, you will learn how to add a license to your Stability AI-Generated image so that if others want to use it, they must properly license it from you.

0. Before you Start

There are a few steps you have to complete before you can start the tutorial.

You will need to install Node.js and npm. If you’ve coded before, you likely have these.
Add your Story Network Testnet wallet’s private key to .env file:

.env
WALLET_PRIVATE_KEY=

Go to the Pinata dashboard and create a new API key and a gateway. Add the JWT along with the gateway to your .env file:

.env
PINATA_JWT=
PINATA_GATEWAY=

Go to Stability and create a new API key. Add the new key to your .env file:

Stability Credits

In order to generate an image, you’ll need Stability credits. If you just created an account, you will probably have a free trial that will give you a few credits to start with.

.env
STABILITY_API_KEY=

Add your preferred RPC URL to your .env file. You can just use the public default one we provide:

.env
RPC_PROVIDER_URL=https://aeneid.storyrpc.io

Install the dependencies:

Terminal
npm install @story-protocol/core-sdk pinata-web3 viem axios sharp form-data

1. Generate an Image

You can follow the Stability API Reference to use the model of your choice. For this tutorial, we’ll be using Stability’s Stable Image Core generate endpoint to generate an image. The below is taken directly from their documentation.

Create a main.ts file and add the following code:

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";

async function main() {
  const payload = {
    prompt: "Lighthouse on a cliff overlooking the ocean",
    output_format: "png",
  };

  const response = await axios.postForm(
    `https://api.stability.ai/v2beta/stable-image/generate/core`,
    axios.toFormData(payload, new FormData()),
    {
      validateStatus: undefined,
      responseType: "arraybuffer",
      headers: {
        Authorization: `Bearer ${process.env.STABILITY_API_KEY}`,
        Accept: "image/*",
      },
    }
  );
}

main();

1.5. (Optional) Condense the Image

Stability generates images that are heavy in size, and therefore expensive to store. Optionally, we can condense the produced image for faster loading speeds and less expensive storage costs.

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";

async function main() {
  // previous code here ...

  const condensedImgBuffer = await sharp(response.data)
    .png({ quality: 10 }) // Adjust the quality value as needed (between 0 and 100)
    .toBuffer();
}

main();

2. Store Image in IPFS

Now that we have our image, we need to store it on IPFS so we can get a URL back to access it. In this tutorial we’ll be using Pinata, a decentralized storage solution that makes storing images easy.

In a separate file uploadToIpfs.ts, create a function uploadBlobToIPFS that uploads our buffer to IPFS:

uploadToIpfs.ts
import { PinataSDK } from "pinata-web3";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT,
  // you can put your pinata gateway here, or leave it empty
  pinataGateway: process.env.PINATA_GATEWAY,
});

// upload our image to ipfs by putting it in a public group
export async function uploadBlobToIPFS(
  blob: Blob,
  fileName: string
): Promise<string> {
  const file = new File([blob], fileName, { type: "image/png" });
  const { IpfsHash } = await pinata.upload.file(file);
  return IpfsHash;
}

Back in the main file, call the uploadBlobToIPFS function to store our image:

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS } from "./uploadToIpfs.ts";

async function main() {
  // previous code here ...

  // convert the buffer to a blob
  const blob = new Blob([condensedImgBuffer], { type: "image/png" });
  // store the blob on ipfs
  const imageCid = await uploadBlobToIPFS(blob, "lighthouse.png");
}

main();

3. Set up your Story Config

Now that we have generated and stored our image, we can register the image as IP on Story. First, let’s set up our config. In a utils.ts file, add the following code:

Associated docs: TypeScript SDK Setup

utils.ts
import { StoryClient, StoryConfig } from "@story-protocol/core-sdk";
import { http } from "viem";
import { privateKeyToAccount, Address, Account } from "viem/accounts";

const privateKey: Address = `0x${process.env.WALLET_PRIVATE_KEY}`;
export const account: Account = privateKeyToAccount(privateKey);

const config: StoryConfig = {
  account: account,
  transport: http(process.env.RPC_PROVIDER_URL),
  chainId: "aeneid",
};
export const client = StoryClient.newClient(config);

4. Set up your IP Metadata

View the IPA Metadata Standard and construct the metadata for your IP. Properly format your metadata as shown below:

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS } from "./uploadToIpfs.ts";
import { client, account } from "./utils";

async function main() {
  // previous code here ...

  const ipMetadata = {
    title: "Lighthouse",
    description: "A generated picture of a lighthouse.",
    createdAt: "1728401700",
    image: process.env.PINATA_GATEWAY + "/files/" + imageCid,
    imageHash: "0x...", // a hash of the image
    mediaUrl: process.env.PINATA_GATEWAY + "/files/" + imageCid,
    mediaHash: "0x...", // a hash of the image
    mediaType: "image/png",
    creators: [
      {
        name: "Jacob Tucker",
        address: "0x67ee74EE04A0E6d14Ca6C27428B27F3EFd5CD084",
        description: "A cool dev rel person.",
        contributionPercent: 100,
        socialMedia: [
          {
            platform: "Twitter",
            url: "https://x.com/jacobmtucker",
          },
        ],
      },
    ],
  };
}

main();

5. Set up your NFT Metadata

The NFT Metadata follows the ERC-721 Metadata Standard.

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS } from "./uploadToIpfs.ts";
import { client, account } from "./utils";

async function main() {
  // previous code here ...

  const nftMetadata = {
    name: "Ownership NFT",
    description:
      "This NFT represents ownership of the image generated by Stability",
    image: process.env.PINATA_GATEWAY + "/files/" + imageCid,
    attributes: [
      {
        key: "Model",
        value: "Stability",
      },
      {
        key: "Service",
        value: "Stable Image Core",
      },
      {
        key: "Prompt",
        value: "Lighthouse on a cliff overlooking the ocean",
      },
    ],
  };
}

main();

6. Upload your IP and NFT Metadata to IPFS

In the uploadToIpfs.ts file, create a function to upload your IP & NFT Metadata objects to IPFS:

uploadToIpfs.ts
// previous code here ...

export async function uploadJSONToIPFS(jsonMetadata: any): Promise<string> {
  const { IpfsHash } = await pinata.upload.json(jsonMetadata);
  return IpfsHash;
}

You can then use that function to upload your metadata, as shown below:

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS, uploadJSONToIPFS } from "./uploadToIpfs.ts";
import { client, account } from "./utils";
import { createHash } from "crypto";

async function main() {
  // previous code here ...

  const ipIpfsHash = await uploadJSONToIPFS(ipMetadata);
  const ipHash = createHash("sha256")
    .update(JSON.stringify(ipMetadata))
    .digest("hex");
  const nftIpfsHash = await uploadJSONToIPFS(nftMetadata);
  const nftHash = createHash("sha256")
    .update(JSON.stringify(nftMetadata))
    .digest("hex");
}

main();

7. Create License Terms

When registering your image on Story, you can attach License Terms to the IP. These are real, legally binding terms enforced on-chain by the Licensing Module, disputable by the Dispute Module, and in the worst case, able to be enforced off-chain in court through traditional means.

Let’s say we want to monetize our image such that every time someone wants to use it (on merch, advertisement, or whatever) they have to pay an initial minting fee of 10 $WIP. Additionally, every time they earn revenue on derivative work, they owe 5% revenue back as royalty.

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS, uploadJSONToIPFS } from "./uploadToIpfs.ts";
import { client, account } from "./utils";
import { createHash } from "crypto";
import { LicenseTerms, WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
import { zeroAddress, parseEther } from "viem";

async function main() {
  // previous code here ...

  const commercialRemixTerms: LicenseTerms = {
    transferable: true,
    royaltyPolicy: "0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E", // RoyaltyPolicyLAP address from https://docs.story.foundation/developers/deployed-smart-contracts
    defaultMintingFee: parseEther("1"), // 1 $WIP
    expiration: BigInt(0),
    commercialUse: true,
    commercialAttribution: true, // must give us attribution
    commercializerChecker: zeroAddress,
    commercializerCheckerData: zeroAddress,
    commercialRevShare: 5, // can claim 50% of derivative revenue
    commercialRevCeiling: BigInt(0),
    derivativesAllowed: true,
    derivativesAttribution: true,
    derivativesApproval: false,
    derivativesReciprocal: true,
    derivativeRevCeiling: BigInt(0),
    currency: WIP_TOKEN_ADDRESS,
    uri: "",
  };
}

main();

8. Register an NFT as an IP Asset

Next we will mint an NFT, register it as an IP Asset, set License Terms on the IP, and then set both NFT & IP metadata.

Luckily, we can use the mintAndRegisterIp function to mint an NFT and register it as an IP Asset in the same transaction.

This function needs an SPG NFT Contract to mint from. For simplicity, you can use a public collection we have created for you on Aeneid testnet: 0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc.

Creating your own custom ERC-721 collection

Using the public collection we provide for you is fine, but when you do this for real, you should make your own NFT Collection for your IPs. You can do this in 2 ways:

Deploy a contract that implements the ISPGNFT interface, or use the SDK’s createNFTCollection function (shown below) to do it for you. This will give you your own SPG NFT Collection that only you can mint from.

createSpgNftCollection.ts
import { zeroAddress } from "viem";
import { client } from "./utils";

async function createSpgNftCollection() {
  const newCollection = await client.nftClient.createNFTCollection({
    name: "Test NFTs",
    symbol: "TEST",
    isPublicMinting: false,
    mintOpen: true,
    mintFeeRecipient: zeroAddress,
    contractURI: "",
    txOptions: { waitForTransaction: true },
  });

  console.log(
    `New SPG NFT collection created at transaction hash ${newCollection.txHash}`
  );
  console.log(`NFT contract address: ${newCollection.spgNftContract}`);
}

createSpgNftCollection();

Create a custom ERC-721 NFT collection on your own and use the register function - providing an nftContract and tokenId - instead of using the mintAndRegisterIp function. See a working code example here. This is helpful if you already have a custom NFT contract that has your own custom logic, or if your IPs themselves are NFTs.

Associated Docs: ipAsset.mintAndRegisterIp

main.ts
import fs from "fs";
import axios from "axios";
import FormData from "form-data";
import { uploadBlobToIPFS, uploadJSONToIPFS } from "./uploadToIpfs.ts";
import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
import { client, account } from "./utils";
import { createHash } from "crypto";
import { LicenseTerms } from "@story-protocol/core-sdk";
import { zeroAddress, parseEther, Address } from "viem";

async function main() {
  // previous code here ...

  const response = await client.ipAsset.mintAndRegisterIpAssetWithPilTerms({
    spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc",
    // the terms we created in the previous step
    licenseTermsData: [{ terms: commercialRemixTerms }],
    ipMetadata: {
      ipMetadataURI: process.env.PINATA_GATEWAY + "/files/" + ipIpfsHash,
      ipMetadataHash: `0x${ipHash}`,
      nftMetadataURI: process.env.PINATA_GATEWAY + "/files/" + nftIpfsHash,
      nftMetadataHash: `0x${nftHash}`,
    },
    txOptions: { waitForTransaction: true },
  });

  console.log(
    `Root IPA created at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`
  );
  console.log(
    `View on the explorer: https://aeneid.explorer.story.foundation/ipa/${response.ipId}`
  );
}

main();

9. Done!

Congratulations! Now your image is registered on Story with commercial license terms.

Learn More

Explore more tutorials in our documentation

Get Started

Integration Guides

Tutorials

Register & Monetize Stability Images

The Explanation

0. Before you Start

1. Generate an Image

1.5. (Optional) Condense the Image

2. Store Image in IPFS

3. Set up your Story Config

4. Set up your IP Metadata

5. Set up your NFT Metadata

6. Upload your IP and NFT Metadata to IPFS

7. Create License Terms

8. Register an NFT as an IP Asset

9. Done!

Learn More

Get Started

Integration Guides

Tutorials

​The Explanation

​0. Before you Start

​1. Generate an Image

​1.5. (Optional) Condense the Image

​2. Store Image in IPFS

​3. Set up your Story Config

​4. Set up your IP Metadata

​5. Set up your NFT Metadata

​6. Upload your IP and NFT Metadata to IPFS

​7. Create License Terms

​8. Register an NFT as an IP Asset

​9. Done!

Learn More

The Explanation

0. Before you Start

1. Generate an Image

1.5. (Optional) Condense the Image

2. Store Image in IPFS

3. Set up your Story Config

4. Set up your IP Metadata

5. Set up your NFT Metadata

6. Upload your IP and NFT Metadata to IPFS

7. Create License Terms

8. Register an NFT as an IP Asset

9. Done!