Bundle API

Access 3D model data and assets programmatically with our RESTful API. Retrieve bundle metadata, model files, and poster images for integration into your applications.

API Usage

Examples and documentation for accessing bundle data

JavaScript

// Get bundle metadata
fetch('https://gallery.monocle3d.com/api/bundle/uyYwJJ3eBAEqeWx0PtAJ')
  .then(response => response.json())
  .then(data => {
    console.log('Bundle data:', data)
    // Access 3D model files: data.glb_url, data.usdz_url
    // Access poster image: data.poster_jpg_data_url
  })

Available Endpoints

GET

/bundle/:id

Get bundle metadata including 3D model URLs and poster images

GET

/bundle/:id/poster.jpg

Get the poster image for a bundle

GET

/bundle/:id/poster_mask.png

Get the poster mask image for a bundle

Response Format

Understanding the bundle metadata structure

JSON Response

{
  "created": "2024-01-15T10:30:00.000Z",
  "modified": "2024-01-15T10:30:00.000Z",
  "glb_url": "https://storage.googleapis.com/monocle-models/example.glb",
  "usdz_url": "https://storage.googleapis.com/monocle-models/example.usdz",
  "poster_jpg_url": "https://gallery.monocle3d.com/api/bundle/uyYwJJ3eBAEqeWx0PtAJ/poster.jpg",
  "poster_jpg_data_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "poster_mask_png_url": "https://gallery.monocle3d.com/api/bundle/uyYwJJ3eBAEqeWx0PtAJ/poster_mask.png",
  "poster_mask_png_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "min_coordinate": [-0.063, -0.076, -0.06],
  "max_coordinate": [0.063, 0.076, 0.06],
  "info": {
    "title": "Vintage Camera",
    "email": "photographer@example.com",
    "description": "A beautifully preserved vintage camera from the 1960s",
    "location_name": "Photography Studio"
  },
  "options": {
    "camera_euler_angles": [0.2, 1.5, 0],
    "camera_pan": [0, 0, 0],
    "wall_mounted": false
  }
}

Response Fields

Core Fields

created

Bundle creation timestamp in ISO 8601 format

modified

Last modified timestamp (including info changes) in ISO 8601 format

glb_url

Direct URL to the GLB (binary glTF) 3D model file for web and AR viewing

usdz_url

Direct URL to the USDZ file for iOS AR Quick Look integration

poster_jpg_data_url

Base64 data URL of the poster/preview image of the 3D model for immediate loading

poster_jpg_url

URL to the poster/preview image of the 3D model (used for Open Graph metadata and social sharing)

poster_mask_png_data_url

Base64 data URL of the poster mask image where black is transparent and white is opaque, for immediate loading without additional HTTP requests

poster_mask_png_url

URL to the poster mask image where black is transparent and white is opaque

min_coordinate

Array of [x, y, z] coordinates representing the minimum bounds of the 3D geometry

max_coordinate

Array of [x, y, z] coordinates representing the maximum bounds of the 3D geometry

Info Object

User-editable information about the bundle

info.title

Short title name for the bundle

info.email

Email address associated with the bundle

info.description

Longer multi-line text description of the bundle

info.location_name

Location name associated with the bundle (future)

Options Object

Configuration options for camera positioning and display settings

options.camera_euler_angles

Array of [x, y, z] camera start orientation angles for matching with poster image

options.camera_pan

Array of [x, y, z] camera panning offset for matching with poster image

options.wall_mounted

Boolean indicating if the model is designated as wall-mounted with limited rotation (back-side oriented towards wall)

Poster Construction

Understanding how poster images and masks work together

How Posters Work

The Bundle API provides two types of poster assets that can be used to create compelling preview images for your 3D models:

Simple Poster (poster_jpg_data_url)

A standard JPEG image provided as a base64 data URL that shows the 3D model rendered against a background. This can be displayed directly as a regular image element.

Masked Poster (poster_jpg_data_url + poster_mask_png_data_url)

When both poster and mask data URLs are available, you can create a transparent background effect. The mask image uses black pixels for transparency and white pixels for opacity, allowing the 3D model to appear to "float" without a background.

Implementation Examples

Simple Poster (HTML)

<!-- Simple poster display using data URL -->
<img src="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..." 
     alt="3D Model Preview" 
     style="width: 100%; height: auto;" />

Masked Poster (SVG)

<!-- Masked poster with transparent background using data URLs -->
<svg preserveAspectRatio="xMidYMid" 
     viewBox="0 0 640 480" 
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <mask id="poster-mask">
      <image width="640" height="480" 
             href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />
    </mask>
  </defs>
  <image width="640" height="480" 
         href="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
         mask="url(#poster-mask)" />
</svg>

Dynamic Poster Creation (JavaScript)

// Dynamic poster implementation using data URLs for faster loading
function createPoster(bundleData, containerId) {
  const container = document.getElementById(containerId)
  
  if (!bundleData.poster_mask_png_data_url) {
    // Simple poster using data URL
    const img = document.createElement('img')
    img.src = bundleData.poster_jpg_data_url
    img.alt = bundleData.info.title || '3D Model Preview'
    img.style.cssText = 'width: 100%; height: auto; object-fit: contain;'
    container.appendChild(img)
  } else {
    // Masked poster with transparency using data URLs
    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
    svg.setAttribute('preserveAspectRatio', 'xMidYMid')
    svg.setAttribute('viewBox', '0 0 640 480')
    
    const defs = document.createElementNS('http://www.w3.org/2000/svg', 'defs')
    const mask = document.createElementNS('http://www.w3.org/2000/svg', 'mask')
    const maskId = 'poster-mask-' + Math.random().toString(36).substring(2, 6)
    mask.id = maskId
    
    const maskImage = document.createElementNS('http://www.w3.org/2000/svg', 'image')
    maskImage.setAttribute('width', '640')
    maskImage.setAttribute('height', '480')
    maskImage.setAttribute('href', bundleData.poster_mask_png_data_url)
    
    const posterImage = document.createElementNS('http://www.w3.org/2000/svg', 'image')
    posterImage.setAttribute('width', '640')
    posterImage.setAttribute('height', '480')
    posterImage.setAttribute('href', bundleData.poster_jpg_data_url)
    posterImage.setAttribute('mask', `url(#${maskId})`)
    
    mask.appendChild(maskImage)
    defs.appendChild(mask)
    svg.appendChild(defs)
    svg.appendChild(posterImage)
    container.appendChild(svg)
  }
}

Benefits of Masked Posters

Transparent Backgrounds: Models appear to float without backgrounds
Better Integration: Posters blend seamlessly with your website design
Professional Appearance: Clean, modern look that focuses on the 3D model
Flexible Styling: Easy to overlay on different backgrounds or UI elements

Google Model Viewer Integration

Using the Bundle API with Google's Model Viewer for 3D display

Integration with Google Model Viewer

The Bundle API provides all the necessary data to seamlessly integrate with Google's Model Viewer library. The camera orbit is calculated from the bundle's Euler angles to match the poster image orientation.

Live Demo Available

For a complete live example showing Bundle API integration with Google Model Viewer, visit our gallery site where you can see real bundle data in action.

View Live Demo

Implementation Examples

Complete HTML Example

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
  <style>
    model-viewer {
      width: 100%;
      height: 400px;
    }
  </style>
</head>
<body>
  <model-viewer 
    src="https://storage.googleapis.com/monocle-models/example.glb"
    ios-src="https://storage.googleapis.com/monocle-models/example.usdz"
    poster="https://gallery.monocle3d.com/api/bundle/uyYwJJ3eBAEqeWx0PtAJ/poster.jpg"
    camera-orbit="85.7deg 75deg 100%"
    camera-controls
    ar>
  </model-viewer>
</body>
</html>

Orbit Calculation Function

// Convert Euler angles to Google Model Viewer orbit parameters
const orbitParamsFromEulerAngles = (euler_angles = [0, 0, 0]) => {
  const orbitEuler = euler_angles
  const theta = orbitEuler[1] * (180 / Math.PI)
  const phi = (orbitEuler[0] + Math.PI / 2) * (180 / Math.PI)
  return theta + 'deg ' + phi + 'deg 100%'
}

// Example usage with bundle data
fetch('/api/bundle/uyYwJJ3eBAEqeWx0PtAJ')
  .then(response => response.json())
  .then(data => {
    const orbitParams = orbitParamsFromEulerAngles(data.options.camera_euler_angles)
    
    const modelViewer = document.querySelector('model-viewer')
    modelViewer.cameraOrbit = orbitParams
    modelViewer.src = data.glb_url
    modelViewer.iosSrc = data.usdz_url
    modelViewer.poster = data.poster_jpg_url
  })

Key Features

Automatic Camera Positioning: Uses bundle's camera_euler_angles for consistent viewing
AR Support: Includes both GLB (web) and USDZ (iOS) model files
Poster Integration: Shows poster image while model loads
Interactive Controls: Camera controls for user interaction
Cross-Platform: Works on web, mobile, and AR devices

Getting API Access

How to get started with the Bundle API

Contact Us

Reach out to our team to discuss your integration needs and get API credentials.

Get API Access

Receive Credentials

We'll provide you with partner credentials and access to our development environment.

Start Building

Use our comprehensive API documentation to build your 3D model integration.