How do I add animation or video to my NFT metadata?

Media Format Requirements for NFT Metadata

1. The animation_url field in ERC-721 or ERC-1155 metadata must point to a publicly accessible HTTP(S) endpoint, not raw IPFS or Arweave URIs like ipfs://QmXyZ... or ar://abc123.

2. Valid video formats include .mp4, .webm, and .mov; GIFs are accepted but discouraged for large assets due to size inefficiency and playback limitations.

3. Audio-only NFTs require .mp3, .wav, or .ogg files served over HTTPS, with explicit MIME type declarations in response headers.

4. All media files must be under 100 MB for reliable on-chain indexing by major marketplaces including OpenSea and Blur.

5. File dimensions and aspect ratios should conform to platform-specific display constraints—OpenSea enforces a maximum width of 3200 pixels for videos rendered in collection previews.

Gateway Conversion Rules

1. IPFS links must be rewritten using trusted public gateways: ipfs://QmXyZ... becomes https://ipfs.io/ipfs/QmXyZ... or https://cloudflare-ipfs.com/ipfs/QmXyZ....

2. Arweave identifiers must be prefixed with https://arweave.net/; no trailing slashes or query parameters may be appended.

3. Private gateways such as Pinata or Infura require authentication tokens and are unsuitable for immutable metadata unless the token is embedded in the URL—a practice strongly discouraged due to revocation risk.

4. Gateway fallback logic should never be implemented client-side; metadata must resolve unambiguously without JavaScript intervention.

5. Responses from gateways must return valid Content-Type headers matching the file extension—e.g., video/mp4 for MP4 files—to prevent rendering failures across wallets and explorers.

HTML Rendering Best Practices

1. Use tags exclusively for video content, with mandatory controls, loop, and muted attributes to ensure autoplay compatibility in Chrome, Safari, and MetaMask Mobile.

2. Avoid embedding media via or third-party players—these break deterministic verification and violate OpenSea’s metadata validation policy.

3. Always specify width and height attributes on and elements to prevent layout shifts during lazy loading.

4. Do not rely on inline Base64 encoding for video—it violates size limits, increases JSON bloat, and prevents streaming or partial download.

5. Serve media over HTTP/2 or HTTP/3 with proper caching headers (Cache-Control: public, max-age=31536000) to reduce repeated gateway requests during high-traffic mints.

Contract-Level Animation Handling

1. On Ethereum mainnet, the tokenURI() function must return a static JSON string containing the animation_url field—dynamic resolution via off-chain oracles is unsupported by indexers.

2. For L2 chains like Optimism or Base, verify that the chosen RPC node supports cross-domain media resolution; some nodes strip non-standard response headers required for video streaming.

3. If deploying via third-party minting tools like Manifold Studio or Thirdweb, confirm whether the tool auto-converts ipfs:// to gateway URLs at upload time—or if manual transformation is required before finalizing the metadata CID.

4. Never store animation logic inside smart contract bytecode; animations are purely off-chain presentation concerns and have zero impact on ownership verification or transfer semantics.

5. When using decentralized storage providers, pin the animation file first, then generate the metadata JSON, then pin the JSON itself—reversing this order risks broken references if the animation file is unpinned before the metadata CID is finalized.

Frequently Asked Questions

Q: Can I use YouTube or Vimeo URLs in animation_url?A: No. External embed domains are blocked by all major NFT marketplaces. Only direct file URLs over HTTPS are accepted.

Q: Does animation_url support HLS (.m3u8) streams?A: No. HLS is unsupported in current indexer implementations. Only progressive-download video formats are indexed reliably.

Q: What happens if my video file returns a 404 after minting?A: The NFT will render as blank or show a broken media icon across all platforms. No automatic fallback to image_url is performed.

Q: Is it safe to host animation files on AWS S3 with public ACLs?A: Yes—if bucket policies enforce HTTPS-only access and disable directory listing. However, long-term immutability requires IPFS/Arweave anchoring, not S3.