Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apetopia.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Trait Overlays lets you create visual overlays — frames, badges, effects — that get composited on top of your NFT images on demand. Members request them through a Discord bot command and get the result back instantly as an image attachment.

Open in Apetopia →

Go directly to this feature in your dashboard.

​
What it’s used for

  • Seasonal frames (holiday edition, anniversary overlay)
  • Event badges for giveaway winners or raffle participants
  • Special visual treatment for rare traits or community milestones
  • Any on-demand NFT image composition you want members to trigger in Discord

​
Creating an overlay

  1. Go to Metadata & Assets → Trait Overlays
  2. Click New Overlay
  3. Select the collection this overlay belongs to
  4. Give it a short code (e.g. gm, winner, halloween) — this is what members type in Discord. Codes must be unique across all your overlays.
  5. Give it a display name (shown in the bot’s overlay list)
  6. Upload your overlay image (transparent PNG recommended — it’s composited on top of the NFT image). Dimensions are auto-detected from the file.
  7. Click Create Overlay
Once created, the edit form opens right away so you can add variants and exclusions without any extra steps.

​
Trait variants

By default, all NFTs in the collection use the same overlay image. You can add variants to swap the overlay image based on a specific trait:
  • Select a Trait Type from the dropdown (loaded from your collection’s NFT data)
  • Select a Trait Value (loaded automatically once you pick a type)
  • Upload the variant image to use for NFTs with that trait
Example: NFTs with Fur = Gold get a gold-colored frame instead of the default silver one.

​
Exclusions

You can block specific trait combinations from using an overlay, with an optional custom message shown to the member when they try.
  • Select the trait type and value to exclude
  • Add an optional custom message (e.g. "Zombie NFTs are not eligible for this overlay.")
If no message is set, the bot uses a default response.

​
Editing an overlay

Click any overlay in the list to open the editor. From there you can update the code, name, and image, and manage variants and exclusions — all in one place.

​
How members use it in Discord

Members run a command in your server — for example: 
/overlay 42 gm
Where 42 is their NFT number and gm is the overlay code. Your Discord bot posts the composited PNG back as a message attachment. To see all available overlay codes, members can run: 
/overlays
The bot replies with the full list of active overlay codes, their names, and which collection they belong to.
Trait Overlays generate composited images on the fly — they do not modify the on-chain metadata or stored image. To permanently update the NFT’s on-chain image, use the Update Asset tool.