How to structure Shopify video and 3D model metadata for AI search

Pendium provides a systematic approach for e-commerce brands to resolve a major blind spot: major AI systems cannot natively watch videos or spin 3D models on product pages. To make these high-value visual assets visible to conversational search models like ChatGPT and Gemini, Shopify merchants must expose the underlying metadata in a structured, machine-readable format. Our platform analyzes this exact data layer to ensure your Shopify store translates visual proof into server-rendered text using the Shopify GraphQL Admin API and standard JSON-LD schema. By structuring this metadata correctly, you convert visual assets into extractable, citable facts that AI search engines can confidently use to recommend your products.

The invisible layer that dictates AI indexing

When an LLM crawler like GPTBot or ClaudeBot arrives on your Shopify product page, it reads the raw, server-rendered HTML. It does not click play, scroll through media carousels, or run JavaScript heavy players. It extracts the raw code and compiles text-based associations.

A high-production video or an interactive 3D model is functionally a blank space to these systems. While a human shopper relies on visual media to verify product quality, the retrieval systems powering AI search rely entirely on structured text. If a creator in a video explains that your skincare product clears eczema in five days, that claim remains locked inside the binary file unless it is mirrored in the markup.

This is where the discipline of Answer Engine Optimization (AEO) becomes practical. AI engines do not guess; they cite facts from structures they can read with high confidence. To get named in conversational search results, you must transform your rich media assets into explicit key-value pairs that are directly accessible to LLM crawlers.

The table below outlines how human shoppers and AI crawlers process product media differently:

Without a concrete textual representation, your most persuasive merchandising assets are entirely dropped from the candidate pool when an AI engine constructs its shopping recommendations.

Configure the Shopify GraphQL media object correctly

To establish machine-readable data, you must begin at the data source. Shopify handles images, videos, and 3D models within a unified file system accessible through the GraphQL Admin API. By defining your media assets correctly at this stage, you build the foundation for downstream schema generation.

When using Pendium to evaluate your site health, we often trace recommendation gaps back to incorrectly classified files. The GraphQL Admin API manages files independently of products, meaning every file receives a unique ID. You must register these assets with the correct MediaContentType enums to make them referenceable.

mutation createProductMedia($productId: ID!, $media: [CreateMediaInput!]!) {
  productCreateMedia(productId: $productId, media: $media) {
    media {
      id
      mediaContentType
      alt
      status
    }
    userErrors {
      field
      message
    }
  }
}

When executing this mutation, pay close attention to the mediaContentType and the alt string. The alt string is not just for accessibility screen readers; it is the primary vector an AI engine uses to build conceptual associations with your product images and files.

Differentiating video formats

Shopify distinguishes between hosted videos and externally hosted files. A Shopify-hosted video uses the VIDEO content type. This format is preferred because Shopify's CDN serves adaptive streaming formats directly in the server response, allowing bots to see clean source URLs.

An external video hosted on YouTube or Vimeo uses the EXTERNAL_VIDEO content type. While convenient, external embeds introduce JavaScript-heavy wrappers that AI crawlers frequently ignore. When mapping an external video, you must explicitly populate the original source metadata. This prevents crawlers from treating the iframe as unreadable third-party script.

Structuring 3D model source files

A 3D model uses the MODEL_3D content type. Shopify stores these models as .glb or .usdz files. Because these files contain highly structured geographic and material data, they are technically rich in text data internally, but crawlers do not unzip them during a web crawl.

To bypass this, you must write highly descriptive alt text for every 3D model. If you upload a 3D model of an ergonomic office chair, your alt text should read: "3D interactive model of the Ergonomic Task Chair showing the 90-degree adjustable armrests, lumbar support, and mesh back material." This descriptive string allows search engines to associate concrete physical specifications with the visual asset.

{
  "alt": "3D interactive model of the Ergonomic Task Chair showing the 90-degree adjustable armrests, lumbar support, and mesh back material.",
  "mediaContentType": "MODEL_3D",
  "originalSource": "https://cdn.shopify.com/files/chair-model.glb"
}

Wrap rich media in JSON-LD product schema

Setting up your backend files is only the first step. To ensure crawlers ingest your media specs, you must render those assets in JSON-LD structured data on your live storefront. Research on Structured Data for AI Search demonstrates that generative engines favor structured key-value pairs over raw body text because structured data is easily parsed into a database.

Your Shopify theme should dynamically loop through product.media and generate corresponding VideoObject or 3DModel schema nested within your primary Product schema. This structure explicitly links the media files to the product identity.

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "Ergonomic Task Chair",
  "image": "https://cdn.shopify.com/files/chair-image.jpg",
  "description": "Premium task chair designed for spinal support.",
  "video": {
    "@type": "VideoObject",
    "name": "Adjusting the Ergonomic Task Chair",
    "description": "A step-by-step demonstration of the adjustable lumbar support and height levers.",
    "thumbnailUrl": "https://cdn.shopify.com/files/video-thumbnail.jpg",
    "uploadDate": "2026-03-15T08:00:00Z",
    "contentUrl": "https://cdn.shopify.com/files/chair-adjustment-720p.mp4",
    "embedUrl": "https://yourdomain.com/media/player?id=102938"
  }
}
</script>

If your schema only lists the price and title, AI platforms will miss the detailed proof contained in your video walkthroughs. For additional schema issues, consult our guide on how to fix the Shopify schema bug hiding your reviews from AI search to ensure your rating data is similarly exposed.

Mapping media to schema.org standards

When mapping your video assets, the description field within VideoObject is where you should place the video's full text transcript or a dense summary of its key points. If your video is a product review or user-generated content (UGC), use the transcript text to outline exactly what claims are made.

For 3D models, there is no direct, universally parsed 3DModel tag in basic schema.org definitions. Instead, use the subjectOf property on the Product schema, pointing to a CreativeWork that hosts the 3D model container. Inside this block, specify that the asset contains spatial interactive configurations. This signals to multimodal engines that you offer spatial assets for virtual try-on or AR viewing.

Handling asynchronous processing gaps

A common mistake in Shopify media pipelines is attempting to fetch file URLs immediately after executing a creation mutation. When you send a video or 3D file to Shopify's CDN, the system processes it asynchronously. The file status will show as PROCESSING before changing to READY.

query checkFileStatus($id: ID!) {
  node(id: $id) {
    ... on MediaImage {
      status
    }
    ... on Video {
      status
      sources {
        url
      }
    }
  }
}

If your theme attempts to render JSON-LD schema while the asset status is processing, the output will lack valid URLs. Implement a polling script or a webhook listener that waits for Shopify to return a READY state before writing the file URLs into your theme's metadata storage or metafields.

Audit the parsed output and measure visibility

Once your GraphQL mutations are configured and your JSON-LD schema is rendering, you must verify that AI search engines can actually parse the data. AI visibility is not a static score; it changes based on how cleanly your data layers are updated and represented.

To run a basic audit, open your Shopify product page, view the source code, and isolate the JSON-LD blocks. Copy the raw schema and run it through syntax validators to ensure there are no trailing commas or missing closing brackets. A single syntax error will invalidate the entire block, causing bots to ignore all nested media definitions.

For a deeper analysis of potential crawlers blocks, you should review our walkthrough on how to audit your Shopify catalog for AI search blockers. This process helps you identify whether your robots.txt or javascript configurations are accidentally blocking bots from reading your asset URLs.

Additionally, monitor how these changes impact actual conversational search queries. Ask ChatGPT or Gemini highly specific questions, such as "which ergonomic chair has 90-degree adjustable armrests?" If your 3D model alt text and JSON-LD schema are properly structured, the AI engine should extract that exact specification and cite your store as the source.

If you want to see how AI platforms currently perceive your brand's digital storefront, run a free AI Visibility Scan on Pendium.ai. The scan analyzes your online presence across seven major platforms in two minutes, showing you the exact visibility gaps that are costing you recommendations. To understand how we help brands scale these workflows across entire catalogs, explore our AI visibility tools for marketing teams or book a direct demo at cal.com/team/pendium/demo.