Upload, validate and publish 3D models

​

Goal

​

Prerequisites

• An owned or licensed GLB or supplied USDZ in a governed Assets bucket.
• Model preparation enabled for the selected space and process permission.
• A separately uploaded approved poster; optional supplied USDZ for the Apple Quick Look path.

​

Workflow

​

3D viewing, rendering and AR

​

Prepare a supported GLB

• Use GLB version 2 with embedded resources. External URLs and data-URL resources are rejected; package textures into the GLB rather than depending on a remote texture host.
• Source size is at most 100 MiB. The geometry budget is 100,000 triangles and 300,000 vertices, including scene instances. Keep at most one animation and one UV set.
• Supported materials are core PBR, unlit and texture-transform extensions with embedded PNG/JPEG textures. Draco, Meshopt and unsupported extensions are rejected.
• Skins are bounded to 254 joints and four weights per vertex. A model with a small file size can still exceed scene/geometry/texture limits.
• Validated GLB output is capped at 10 MiB, 10 materials and 2,048-pixel textures. Processing deduplicates, prunes and resizes textures; it does not simplify arbitrary excess geometry or provide studio rendering.

​

Upload and validate in the dashboard

​

Read and request model processing through the SDK

const asset = await sdk.assets.get(assetId)
const state = await sdk.assets.dam.models(asset.id)
if (!state.pilot_enabled) throw new Error('Model preparation is unavailable for this space')
const job = await sdk.assets.dam.processModel(asset.id, asset.revision, crypto.randomUUID())
// Later, refresh status; avoid a tight polling loop.
const refreshed = await sdk.assets.dam.models(asset.id)
const current = refreshed.packages.filter(item => item.version_id === asset.current_version_id)
const ready = current.find(item => item.status === 'ready')

​

Inspect the result before approval

​

Supply USDZ for Quick Look

​

Add a poster and publish

​

Visitor controls and AR authorization

​

Troubleshoot models and AR

• Scan pending or failed: complete/recover malware scanning before requesting model processing.
• Unsupported extension or remote dependency: export the supported embedded GLB profile; do not merely rename another format to .glb.
• Geometry/material/output budget exceeded: simplify the source in your modeling tool and upload a new version. The native optimizer is not a general geometry-reduction service.
• Ready package exists only for an old version: prepare the current version and create a new reviewed publication snapshot.
• No poster or no publication rendition: finish processing the companion image/model and select valid returned references.
• AR unavailable: check policy, rights, gallery/publication revision, supplied USDZ where required, and actual device/browser support. Do not assume rendering a turntable fixes AR.

​

Go, Python and PHP: validate the current model and track its job

package docsexample

import (
	"context"
	"fmt"
	stackshift "github.com/stackshiftCloud/assets-go"
)

func prepareModel(ctx context.Context, dam *stackshift.AssetDAMClient, assetID, requestKey string) (map[string]any, error) {
	workspace, err := dam.Models(ctx, assetID)
	if err != nil {
		return nil, err
	}
	if workspace["pilot_enabled"] != true {
		return nil, fmt.Errorf("model preparation is disabled for this space")
	}
	editor, err := dam.MetadataEditor(ctx, assetID)
	if err != nil {
		return nil, err
	}
	revision, ok := editor["revision"].(float64)
	if !ok {
		return nil, fmt.Errorf("missing current asset revision")
	}
	return dam.ProcessModel(ctx, assetID, int64(revision), requestKey)
}

def prepare_model(dam, asset_id, request_key):
    workspace = dam.models(asset_id)
    if not workspace["pilot_enabled"]:
        raise RuntimeError("Model preparation is disabled for this space")
    editor = dam.metadata_editor(asset_id)
    return dam.process_model(asset_id, editor["revision"], request_key)

function prepareModel(\StackShift\AssetDAMClient $dam, string $assetId, string $requestKey): array {
    $workspace = $dam->models($assetId);
    if (!$workspace['pilot_enabled']) {
        throw new \RuntimeException('Model preparation is disabled for this space');
    }
    $editor = $dam->metadataEditor($assetId);
    return $dam->processModel($assetId, $editor['revision'], $requestKey);
}

​

HTTP operations for this workflow

​

Model workspace and job response fields

​

Expected result

​

Common failures

​

Related guides