OpenUSD Assets
3D Assets searches USD-family, GLB and glTF assets, separate from AI model identities. Existing OpenUSD routes and UUIDs remain compatible. Its navigation entry follows Benchmarks. The public 3D Assets page initially shows the latest 18 indexed assets, including assets whose preview image is missing, still being checked or unusable. Keyword searches cover the full index by default. Dataset, source representation format and the optional “With previews” filter can refine the results.
Opening an asset detail automatically starts its interactive 3D preview. Its cached poster stays visible while the viewer module loads. The full-width viewer shows a selectable Materials or Studio view beside a fixed Wireframe view; orbit, pan, zoom and reset stay linked in both directions. Asset metadata follows below the viewer. Collection cards never load scenes or the heavy viewer bundle. Source metadata and downloads remain accessible without JavaScript or WebGL. The root-file byte count is not the complete dependency download size.
Search and asset representation
GET /api/v1/openusd/assets accepts q, dataset, format, preview, limit and offset. format matches the original or explicitly related usd, usda, usdc, usdz, glb or gltf representation. limit defaults to 18 and accepts 1–100; offset accepts 0–1,000,000. Search text is limited to 500 characters.
The API and website default to preview=all so neither the initial gallery nor a keyword search silently omits an asset without a poster. “With previews” explicitly selects preview=available; “available” means a validated cached poster exists, and does not certify that every scene feature can be rendered interactively. Pagination and the result count use the selected filters; any second count describes the complete active asset index. Canonical URLs preserve preview=available, while the default preview=all is omitted.
The response contains data, total_count for the requested filters, unfiltered_total for all active assets, preview_total for active assets with cached posters, limit, offset and indexing. Entries sort by source update time, then stable UUID. A dataset update fallback remains labelled as a dataset update, never an invented asset publication date. GET /api/v1/openusd/assets/{id} returns one active asset; GET /api/v1/openusd/datasets exposes source coverage and scan status.
Each asset has one stable TensorTrace UUID for an exact Hugging Face dataset/root-file pair. A new repository commit updates that identity rather than creating a duplicate. Parser version 6 selects logical roots from observed SimReady manifests and recognized package entrypoints. Internal payloads, materials and declared component files do not become separate cards. Source-native package names take precedence over generic filenames such as model.usdc; informative ancestor paths provide a fallback.
Benchmark reconstruction outputs retain their source role, reference asset, run and reconstruction variant. They are labelled as reconstruction candidates rather than presented as unnamed, equivalent reference assets. For recognized SimReadyBench submissions, only observed candidate captures from the same run, reference asset and repetition can become posters. Copied task/reference thumbnails remain attributed in metadata.source_presentation_images; they are never substituted for missing candidate captures. Descriptive fields, dimensions and license statements from source manifests remain attributed source claims, not independently measured facts.
Original file downloads
GET /api/v1/openusd/assets/{id}/download streams the original indexed root file as an attachment. The metadata File value uses this same-origin endpoint, so Git-backed USD text downloads reliably even when Hugging Face serves it inline. Provider remains an external link to the upstream file page, with a validated dataset-page fallback. The endpoint never packages dependencies, changes variants or substitutes the interactive GLB representation.
The active asset UUID selects its stored dataset, immutable revision and path; callers cannot supply a URL. Acquisition uses the shared public-IP/DNS-pinned transport, disables proxies and automatic decompression, and manually validates every redirect against Hugging Face's HTTPS infrastructure. No source credentials, cookies, redirect locations or inline content-disposition are forwarded. The response preserves file bytes and the original basename, uses Content-Disposition: attachment with an RFC 5987 UTF-8 filename, and includes nosniff and no-store headers.
Files with an indexed size above 512 MiB redirect to their pinned Hugging Face URL with download=true, retaining native large-file downloads without proxying those bytes. Smaller files stream with backpressure, a 512 MiB proxy limit, a 120-second total source/transfer deadline and eight concurrent transfers. Disconnecting drops the upstream response and releases its permit; no database connection is held while streaming. Expected file sizes are checked, including at end of stream. Range/resume is not supported. Failures before headers return a safe error; a later size, deadline or network failure aborts the transfer rather than producing a successful truncated file. HEAD returns attachment headers from stored metadata only, without contacting Hugging Face; it does not verify current upstream availability. Ordinary API reads and page rendering never trigger this download path.
Posters and interactive preview
source_thumbnail_url preserves a revision-pinned HF image URL or an observed per-object provider image URL from pinned annotations. Provider-hosted image bytes are validated and cached by the worker; the external URL itself is not a provider immutability guarantee. Public thumbnail_url is either null or the local endpoint /api/v1/openusd/assets/{id}/thumbnail?v={media_version}. Browsers do not repeatedly test or transform remote thumbnails. The media object reports pending, ready, missing, failed or unusable, with available dimensions and check time. A missing, transparent or blank source render is not displayed as a successful preview. For opaque near-uniform image borders, media.background_color contains a worker-measured #RRGGBB gutter colour. Uncertain or transparent borders return null; the original image pixels are not recoloured.
The serial-worker source hfOpenUsdMedia checks observed source-image candidates, follows only supported source hosts, validates image bounds and rejects blank or transparent renders. Accepted inputs are capped at 4 MiB and 8192 pixels per dimension with a 64 MiB decoder allocation limit. Posters fit within 768×768 and are stored as WebP capped at 512 KiB. Acquisition is bounded and retryable; rate limits defer subsequent work. This first stage preserves and normalizes real source images. If no usable image exists, the same worker generates an illustrative 3D fallback as described below.
A media_key incorporates the source revision, observed image candidates, declared alternative preview and poster-policy version. Updating any of these prevents an old cached poster or failed check from being reused for a new representation. Source posters use their input key as the media version; generated posters append the normalized image SHA-256. Ready posters use local versioned URLs, ETags and immutable cache headers; missing or obsolete versions return 404. HTTP page and image reads never start acquisition.
USD preview uses the locally bundled official Hugging Face USD loader. When a recognized package manifest or scoped publisher documentation explicitly links the original USD root to an observed GLB file at the same revision, preview describes that browser-ready alternative. Its format, path, URL, byte size and source-manifest relationship remain available alongside the original USD identity and download. The viewer tries this declared alternative first and falls back to the original USD if it fails. It never pairs files by similar names or replaces the USD source identity with a GLB identity.
The linked views share one source load, composed scene and WebGL renderer. Material loading includes normal and data maps, with decoded texture dimensions capped at 2048 pixels and the existing download budgets retained. Desktop views sit side by side and narrow screens stack them. Materials, Studio and Wireframe support appearance and geometry inspection. The viewer has explicit layer, texture, geometry, instance and time budgets, releases resources on navigation, and exposes failures or composition warnings. A browser preview is not a simulation, license approval or guarantee of full renderer fidelity.
The shared usd-preview Rust/WASM facade reuses the pinned upstream parser, composition and mesh extraction for both interactive views and worker posters. It applies bounded, best-effort geometry corrections in a separate in-memory session layer: small surplus index tails are ignored according to the declared face boundaries, and a small number of invalid faces can be omitted while retaining their original face IDs and material-subset/uniform-data mappings. It never guesses missing vertices or changes source buffers, revisions, download files or model identities. Valid geometry is not rewritten. Animated topology, ambiguous face-varying attributes, prototype authoring, nonfinite data and excessive damage remain subject to strict failure handling. Correctly sized face-varying data can remain unchanged for tail-only compatibility; partial-face corrections never discard or shift UVs/normals silently.
Affected models have a small amber ! next to preview statistics and on cards when the worker has recorded the fault. Hover or keyboard focus explains that the preview may be approximate and the source may need repair before use. geometry-repaired and geometry-partial distinguish approximate recovery from unrenderable geometry. Browser capability/triangle limits alone do not mark the source corrupt. The original model can remain invalid even when a useful approximate preview is available.
When a preview fails, the desktop or stacked mobile viewing area keeps its dimensions. A concise error appears inside that area without a retry button. Unavailable appearance/reset controls stay disabled, and the error is not repeated in a separate limitations panel. Renderable scenes still show warnings about partial fidelity.
Some SimReady sources publish an authored reduced-detail variant for browser use. For verified ALLSIDES packages, metadata.preview_variants identifies /Asset, lod=1 and its revision-pinned publisher documentation. The worker selects it in a temporary stronger USD layer, retaining the original root URL, coordinate metadata, transforms and material bindings. It resolves only selected dependencies, so unused high-detail geometry is not downloaded. Original files are not rewritten; missing variants fall back to the source selection with a warning. The preview labels a selected lower-detail representation.
Preview downloads target about 10 MiB, with a hard 32 MiB per-resource limit and 64 MiB combined scene budget, including dependencies. These are TensorTrace product budgets, not glTF format limits or a loading-time guarantee. Unknown sizes are counted while streaming; a small USD or JSON root does not establish the size of its referenced geometry and textures. The 2-million-triangle and separate decoder/texture guards remain in force.
The existing verified ALLSIDES reduced-detail profile retains a 96 MiB combined-download and source-texture allowance for its five PBR maps. Only the exact dataset, revision, path and sole /Asset lod=1 publisher-README proof select that exception; it never raises the 32 MiB per-resource cap. glTF decoded geometry and GPU texture allocations have independent limits described below. A scene that exceeds a budget is reported as resource_limit, not corrupt or empty. Search metadata, original downloads and valid publisher posters remain available. Volumes, unsupported curves/points and custom MDL shaders may still require the original application.
Scene check status
render is null before the worker checks the current immutable input. It then
contains status, error_code, message, checked_at, attempts, retry_at
and warnings. Public warnings are a bounded list of known {code,message}
categories with fixed safe text; internal paths, URLs and renderer context are
not copied into this summary. An explicit empty summary supersedes earlier
poster warnings after a clean check.
It is independent of media: a valid publisher thumbnail can remain ready when
the actual scene is invalid. Successful checks use ready; transient asset
failures use failed and retry later; empty or malformed sources and fixed
resource limits use unusable. infrastructure identifies startup, renderer
protocol or WebGL failures and pauses the bounded batch without classifying
other assets. Changed source inputs become eligible again. The compatibility
policy prioritizes older invalid/empty checks and partial invalid-geometry
checks once; valid ready checks and genuine source posters are retained, and
transient failures continue to respect their retry deadline.
Each result is persisted before advancing. Structured worker logs identify the
asset, dataset, duration, geometry counts, status and error category; refresh
receipts retain the bounded per-batch outcomes. Full private diagnostics are
stored by (asset_id,input_key) in openusd_render_checks. Asset failures do not
block the next eligible asset. Source 429 responses defer the shared source queue.
Diagnostic text is for display; clients should use error_code for decisions.
Worker-generated posters
Missing posters never exclude an indexed asset from the default gallery or keyword search. The optional preview=available filter selects only cached images. The worker first validates source images; missing or permanently unusable images receive a bounded render attempt. Image HTTP 401/403 denials are retained as unusable-source evidence, allowing a poster from the independently accessible scene. Network/503 failures remain retryable and HTTP 429 retains its cooldown. Existing valid source posters are retained.
hfOpenUsdMedia checks at most one 3D scene per bounded serial worker turn, with one independently launched, temporary headless Chromium per job. Checks include assets with ready source images; a source image is not proof that its 3D scene can load. When no usable source image exists, a successful check also publishes a fallback poster. Ready source posters retain their bytes, cache key and acquisition metadata. It uses the same local viewer, source-manifest GLB alternative and original-USD fallback, revision-pinned LOD policy, material loading, camera and geometry limits as the interactive page. Generated posters have a ground grid. Source bytes reach the sandboxed browser through the tokenized loopback HTTP bridge, avoiding base64 copies and WebSocket message-size limits in the automation channel. The source allowlist, cancellation and download budgets still apply. Empty, invalid, unsupported or over-budget scenes keep their searchable metadata and source links; they are never published as blank thumbnails. Transient failures retry after a delay, and source 429 cooldown applies to acquisition and rendering alike. Infrastructure failures do not mark every asset permanently unusable.
Each job has a 90-second outer deadline, at most 64 upstream requests, four concurrent fetches, a 32 MiB per-resource cap and a 64 MiB combined source-download budget (96 MiB only for the exact verified LOD profile above). Declared lengths and unknown-length streams are both bounded. Download bytes, request count, elapsed time, decoded geometry and textures are independent budgets. A token-scoped loopback bridge serves only the bundled renderer/WASM and validated Hugging Face dependencies. All remote transfers use the server's public-IP/DNS-pinned transport and manually checked redirects, without source credentials or proxy inheritance. The headless browser does not use a desktop profile or CDP session. Its detached process group is registered with the worker and terminated on cancellation along with in-flight transfers.
Media work is dispatched independently of the five-minute catalog scan, within the same serial admission owner. A committed batch with runnable backlog immediately yields another turn; empty queues, future retries, failures and upstream cooldowns sleep. Due catalog work, provider status and drain are checked between bounded turns. Each turn limits source-image work to four assets, twelve requests, 16 MiB and a 30-second acquisition window, with at most one scene render and one bounded package audit. Other source acquisitions remain serial, so their actual execution time can still delay a turn; this is not a parallel-download or bandwidth-saturation guarantee. Receipt-only media updates acknowledge their own outbox entries and preserve source counters/overview freshness without rebuilding unrelated model, Research and Benchmark projections.
The API distinguishes media.source = huggingface from generated; provenance is null before a media record exists and an empty object for prepared source images; media.generation_version and bounded media.provenance record the renderer/browser version, original revision, selected representation and appearance, geometry counts, warnings and acquisition budgets. source_thumbnail_url remains the upstream candidate, including null when absent. Generated cache URLs combine the asset input key and normalized WebP SHA-256. Ready posters are reused until their source input changes; a new generation policy retries previously unusable attempts but does not discard valid source images. Source images exceeding the fixed download bound are recorded as unusable rather than downloaded repeatedly.
The worker runtime needs Node.js, the pinned clients/web npm dependencies (including playwright-core), the built local viewer/WASM, and a sandbox-capable Chromium installation. TENSORTRACE_OPENUSD_CHROMIUM_PATH selects an absolute dedicated Chromium executable; otherwise Playwright uses its installed browser cache. TENSORTRACE_OPENUSD_NODE can select Node when it is not on the worker PATH. The private deployment configuration and browser cache are never committed. See deployment requirements.
Acquisition and coverage
refresh hfOpenUsd runs through the existing serial worker and durable admission gate. A manual refresh performs one bounded batch, not a complete crawl. Manifest-driven sources can publish useful metadata before their complete annotation inventory finishes; only completion of the matching publication generation can withdraw absent objects. Leave the ordinary serial worker running, or use the existing serve worker/scheduler options, for acquisition to continue. Do not start a second worker alongside an already supervised worker. Production needs no additional crawl daemon, and clients never fetch discovery pages or crawl repositories.
Discovery uses the official public Hugging Face API rather than a fixed repository list. The curated collection supplies seeds; paginated tag, name and 3D queries discover additional repositories. Queries include OpenUSD, USD, USDZ and SimReady, plus modality:3d, 3d, USDA, USDC, Omniverse and Isaac. Each eligible worker batch reserves a bounded discovery turn of at most one list page, even while repository inventories remain unfinished. A completed tag/name discovery cycle is scheduled to run again six hours later, so newly matching repositories can enter the queue.
Repository metadata checks are scheduled independently from discovery and other repositories' large inventories. A repository becomes eligible for another check six hours after its previous check or completed inventory; execution still shares the serial worker's capacity and upstream limits. An unchanged source SHA reuses its published inventory; a changed SHA starts a new revision-pinned inventory. Tree pages, bounded package metadata, exact cursors, staged entries and checksummed request receipts persist before advancing. Publication completes against that pinned revision, and only a completed inventory can withdraw absent roots. Parser-version changes can require reprocessing even when the upstream SHA is unchanged.
New repositories and paused inventories receive round-robin turns. Multiple eligible manually prioritized repositories also rotate, so a large manifest cannot indefinitely retain the priority lane. Manual priority gives ordinary eligible work a turn after at most three consecutive priority batches. Retryable repository failures defer only the affected repository, with exponential retries starting at five minutes and capped at six hours; its pinned cursor, staged inventory and previously published assets are retained. Collection and discovery-list failures have separate retry state and do not block eligible repository work. Three consecutive acquisition failures end the current bounded batch. HTTP 429 retains shared-host cooldown behavior, which manual priority and retries cannot bypass. The existing scheduler persists the next eligible wake time rather than stopping when the queue is temporarily idle. Explicit gated, private, disabled or unavailable sources remain subject to the existing access restrictions; no credentials or access gates are bypassed.
The API's indexing object distinguishes queued work from published coverage:
queued_repositoriescounts repositories waiting for a metadata/inventory turn.partial_inventoriescounts the active and paused revision-pinned inventories.retrying_repositoriescounts repository-specific retry records.discovery_completereports completion of the current discovery cycle, not complete Hugging Face coverage.next_discovery_atis the scheduled start of the next discovery cycle, or null while the current cycle is unfinished.next_check_atis the scheduler's next eligible acquisition wake time, including deferred work, or null when no deferred wake is recorded.
These fields supplement pending, source cooldown/retry times, discovered/indexed dataset counts and the last publication time. An idle queue can still have scheduled future checks. Staged file counts are not model counts, and dataset counts do not certify every repository, dependency or 3D render. Untagged repositories, opaque archive contents and gated content can remain absent; neither a discovery cycle nor an indexed asset implies that its scene has been successfully rendered.
To prioritize a repository refresh, run cargo run --locked -- queue-openusd-dataset owner/repository from server/, then let the scheduler run or invoke cargo run --locked -- refresh hfOpenUsd. The queue operation shares worker admission and locks the crawl checkpoint. It restarts that repository's inventory, preserves unrelated work and published identities, and persists priority across bounded turns subject to the fairness rule above. Completion or permanent source restrictions release priority. All request, byte, time and source-cooldown limits remain in force.
To prioritize an unfinished repository without discarding staged inventory, use cargo run --locked -- resume-openusd-dataset owner/repository. It resumes the existing pinned revision and tree/metadata cursor, retains other paused scans, and shares the same admission, fairness and rate-limit gates. When no partial scan exists, it queues the repository normally. This does not clear an uncertain worker owner or a source cooldown. Assets become searchable after the pinned inventory and its metadata finish publishing.
An unexpected repository identity in a successful metadata response is deferred for that repository, with expected/observed identity evidence. It does not merge the identities, withdraw previously published assets or stop unrelated scans. A later scheduled repository check may reconsider it; access restrictions and shared-host rate-limit gates still apply.
Format-neutral indexing compatibility
The existing /openusd and /api/v1/openusd routes and UUIDs also index public
GLB and glTF files. format=glb and format=gltf are accepted in addition to the
USD-family filters. An explicitly related representation also matches a format
filter; filename similarity does not establish a relationship.
Prepared documents can include object_identity, representations, tags,
author, and source-owned descriptive metadata. Each representation retains its
path, format, immutable URL and relationship basis. The original download URL
continues to select the asset's original file. An optional representation
query parameter selects an exact path from that asset's stored representation
list; arbitrary URLs or unlisted paths are rejected before acquisition.
indexing.counts separates logical asset/method cards, source object identities
and physical representations. indexing.previews_checked counts current scene
checks independently from preview_total (ready posters). Dataset summaries
include manifest/shard progress and archive coverage limits. Objaverse metadata
is joined using the official UID/object-paths manifest and annotation shards;
its per-object rights take precedence over the separate dataset license.
Metadata is searchable before models are downloaded or rendered.
glTF capability and resource policy
GLB and JSON glTF 2.0 use the pinned official Three.js GLTFLoader. The Khronos validator performs bounded source checks; its extension coverage is separate from loader/decoder coverage. Known required capabilities are checked before loading. Unsupported required extensions remain explicit capability errors and do not mark the source corrupt.
| Capability | Preview behavior |
|---|---|
| GLB and JSON glTF 2.0 | Default scene, triangle lists/strips/fans, PBR materials, skins, morph targets and linked views. Point/line-only scenes report unsupported capability. |
| External buffers and images | Relative or absolute references must stay in the exact indexed HF repository and immutable revision. Arbitrary hosts, credentials, mutable revisions, private URLs and ambiguous encoded paths are blocked. Embedded PNG/JPEG/WebP/KTX2 data is bounded. |
| Draco | Official Three.js/Draco glTF decoder, one worker, guarded output geometry and 256 MiB heap-growth ceiling. |
| Meshopt | Official bundled Meshopt decoder; declared decoded count/stride/view sizes are checked before allocation. |
| KTX2 / Basis Universal | Official KTX2Loader/transcoder, LDR ETC1S/UASTC, one worker and 256 MiB heap-growth ceiling. Up to 4096 px native compressed textures; the actual target bytes are checked before GPU upload. Oversized or device-dependent RGBA fallback maps are omitted with a fidelity warning rather than a source-error marker. |
| PNG/JPEG/WebP | Bounded header checks and serial image decoding; source decoded images are capped at 64 MiB and normalized bitmaps at 2048 px. Total GPU texture data is capped at 64 MiB. Required AVIF and other unconfigured image codecs are unsupported; optional AVIF uses the authored core fallback. |
| Legacy SpecularGlossiness | glTF Transform metalRough prepares a temporary modern PBR preview with bounded 1024 px maps. All original bytes, source revision, rights and downloads remain unchanged. |
| Other supported extensions | Punctual lights, texture transforms, mesh quantization/instancing and the native loader's audited PBR extensions are listed in gltfCapabilities. Other required capabilities are rejected explicitly. |
| Animation | Up to 128 clips, actual shared AnimationMixer playback/pause/selection across both panes. Automatic playback selects the first moving clip while keeping static poses selectable. Worker posters use the initial pose. Worker-measured skin counts and bounded clip names/durations supplement source annotations. |
Limits include a 32 MiB root/resource, 64 MiB total acquisition, 64 requests, 128 MiB decoded geometry, 2 million drawn triangles, 10,000 scene nodes/instances, 256 materials, 256 joints per skin and a 20-second decoder deadline inside the 90-second viewer/worker deadline. The 128 MiB decoded-memory guard is not a download allowance. Compressed KTX working allocations are additionally bounded by fixed dimensions, mip count and transcoder heap limits. Source geometry/image errors, resource limits, unsupported capabilities, network failures and graphics-context failures remain distinct.
The download target is informed by Google Scene Viewer guidance, which recommends about 10 MB and has its own 15 MB validator ceiling. TensorTrace deliberately allows a larger bounded input for research assets; Scene Viewer's limits are not universal browser requirements. Cached posters and deferred interactive loading follow model-viewer guidance. Byte budgets are an admission policy, not a claim that every fitting source is supported or that compressed bytes predict GPU memory.
The Web resource worker's HF-only CSP applies to redirects as well as authored references. Worker posters use the same URI/material/geometry policy through the existing public-IP/DNS-pinned, tokenized loopback bridge. Blob URLs, ImageBitmaps, skeleton textures, decoder workers, animation mixers and GPU resources are released on failure, cancellation or navigation. Missing posters do not remove metadata from search.
Prepared counts and search projections
Migration 151 stores catalog visibility, representation formats, object keys and page fingerprints outside large annotation documents. The serial publisher updates per-dataset card/object/representation counts atomically with each partial or completed publication, access restriction and withdrawal. Searches aggregate these prepared counts and use indexed format projections; scoped keyword counts use the stored text indexes. A source file retained for old UUID links is distinct from a visible logical card or an explicitly related representation.
Selected-source indexing.source.inventory_summary exposes annotation-shard progress, manifest paths and unexpanded archives. A completed discovery cycle is never presented as complete model coverage. Progressive metadata publication also updates the ordinary sitemap family; its compact fingerprints avoid rereading large JSON documents to compare every page. The sitemap wrapper preserves earlier non-3D SEO policies.
Verified mirror groups
Identical closed USDZ packages can share one logical card when the server has a trustworthy full HF LFS SHA-256 and a bounded, versioned package-closure receipt. Every packaged layer and authored asset/reference/payload is checked with the pinned SDF reader, including unselected variants. The current usdz-closure-v2 policy also refuses opaque shader/code/clip resources and nonrelative or escaping references whose own dependency closure is unproven. Root USD, GLB and JSON glTF remain separate without equivalent package evidence. Authored reconstruction/method/LOD/preview selections opt out of cross-source fusion. Titles, filenames, Git blob IDs and thumbnails alone never establish identity. Metadata publication never waits for closure downloads; a failed/unproven check leaves the original searchable rows intact.
A confirmed group has a separate persistent UUID; singleton IDs remain unchanged. Group IDs stay bound to the verified bytes when representatives leave or change revision/content. Every original source UUID/detail/download/thumbnail route keeps its original meaning. Group detail/download/thumbnail routes select an eligible equivalent member; returned media/render source IDs and original provenance identify the actual producer. Inspector policy changes invalidate prior closure trust, preserve retry/cooldown deadlines and private evidence history, and requeue bounded verification. The persistent group ID is reused after successful revalidation. An active alias page canonicalizes to its group; sitemaps publish one logical URL.
Responses add group_id, canonical_url, primary_source_id, source_count, prepared publishers/actual authors, and source-attributed sources. Per-source metadata, revision, original downloads, author, uploader/publisher and rights remain distinct; differing license claims do not become a combined grant. Listing responses include up to five sources, detail up to100. GET /api/v1/openusd/assets/{id}/sources?offset=100&limit=100 returns {data,total_count,offset,limit}. The ordinary detail URL accepts sources_offset for a no-JavaScript source page; its canonical remains the bare logical URL.
Dataset, format and keyword predicates must match the same active member. A keyword on any member finds the group without a source filter. Preview availability is shared only within proven equivalent package identity. Counts/pagination use the prepared logical-card projection; indexing.counts.source_aliases, source-object and representation counts retain physical/source distinctions. Inactive/gated members are removed from public source/author/rights aggregates. Worker audit state, SHA verification, retries/cooldowns and a failed-copy/healthy-copy fallback are persisted; only one candidate package is audited per existing admitted media turn. No page or API read acquires package bytes.
On this page
- Search 3D assets ·
GET /openusd/assets - Read one 3D asset ·
GET /openusd/assets/{id} - Read a validated 3D asset thumbnail ·
GET /openusd/assets/{id}/thumbnail - Read 3D dataset indexing coverage ·
GET /openusd/datasets - Download an original 3D asset file ·
GET /openusd/assets/{id}/download - Page original public sources of a logical 3D asset ·
GET /openusd/assets/{id}/sources
Search 3D assets
GET /api/v1/openusd/assets
Reads stored USD, GLB and glTF metadata without upstream acquisition. Public data only; source terms and preview fidelity vary by asset.
Access: public read; no TensorTrace API key.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
q | query | No | string Max. length: 500 | Keywords matched against source-owned names, descriptions, tags, categories, authors, paths and dataset descriptions. |
dataset | query | No | string | Exact HF owner/repository identity. |
format | query | No | string Values: usd, usda, usdc, usdz, glb, gltf | Match the primary format or an explicitly related source representation. |
preview | query | No | string Default: "all"; Values: available, all | Use available for assets with a worker-validated ready thumbnail; all includes assets whose image is missing or still being prepared. |
limit | query | No | integer Default: 18; Minimum: 1; Maximum: 100 | Number of cards per page. |
offset | query | No | integer Default: 0; Minimum: 0; Maximum: 1000000 | Zero-based offset in matching cards. |
Request example
curl 'https://tensortrace.net/api/v1/openusd/assets?limit=1'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Stored OpenUSD result. | object |
400 | Invalid query parameters. | No declared JSON body |
404 | Asset does not exist or is unavailable. | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"title": "example",
"dataset_id": "example",
"dataset_name": "example",
"publisher": "example",
"path": "example",
"format": "usd",
"byte_size": 1,
"thumbnail_url": "example",
"raw_url": "example",
"source_url": "example",
"source_updated_at": "2026-10-05T00:00:00Z",
"updated_scope": "asset",
"revision": "example",
"license": "example",
"categories": [
"example"
],
"metadata": {},
"source_thumbnail_url": "example",
"preview": {
"format": "glb",
"path": "example",
"url": "https://example.com/model",
"byte_size": 1,
"source": "source_manifest"
},
"media": {
"status": "pending",
"width": 1,
"height": 1,
"source": "example",
"updated_at": "2026-10-05T00:00:00Z"
},
"description": "Illustrative model observation; consult live evidence for current specifications."
}
],
"total_count": 1,
"unfiltered_total": 1,
"preview_total": 1,
"limit": 1,
"offset": 0,
"indexing": {
"datasets_discovered": 1,
"datasets_indexed": 1,
"assets_indexed": 1,
"pending": false,
"last_indexed_at": "2026-10-05T00:00:00Z",
"coverage": "example"
}
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
data | array of object | Yes | Bounded asset cards, latest source update first. |
total_count | integer | Yes | Matching active assets before pagination. Minimum: 0 |
unfiltered_total | integer | Yes | All active assets before search or filters. Minimum: 0 |
preview_total | integer | Yes | All active assets with a worker-validated ready thumbnail, before search, dataset, format or preview filtering. Minimum: 0 |
limit | integer | Yes | Requested page size; defaults to 18. Minimum: 1; Maximum: 100 |
offset | integer | Yes | Zero-based matched-result offset. Minimum: 0; Maximum: 1000000 |
indexing | object | Yes |
Read one 3D asset
GET /api/v1/openusd/assets/{id}
Reads stored USD, GLB and glTF metadata without upstream acquisition. Public data only; source terms and preview fidelity vary by asset.
Access: public read; no TensorTrace API key.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
id | path | Yes | string · uuid | Stable TensorTrace 3D asset UUID. |
Request example
curl 'https://tensortrace.net/api/v1/openusd/assets/google'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Stored OpenUSD result. | object |
400 | Invalid query parameters. | No declared JSON body |
404 | Asset does not exist or is unavailable. | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"id": "00000000-0000-4000-8000-000000000001",
"title": "example",
"dataset_id": "example",
"dataset_name": "example",
"publisher": "example",
"path": "example",
"format": "usd",
"byte_size": 1,
"thumbnail_url": "example",
"raw_url": "example",
"source_url": "example",
"source_updated_at": "2026-10-05T00:00:00Z",
"updated_scope": "asset",
"revision": "example",
"license": "example",
"categories": [
"example"
],
"metadata": {},
"source_thumbnail_url": "example",
"preview": {
"format": "glb",
"path": "example",
"url": "https://example.com/model",
"byte_size": 1,
"source": "source_manifest"
},
"media": {
"status": "pending",
"width": 1,
"height": 1,
"source": "example",
"updated_at": "2026-10-05T00:00:00Z"
},
"description": "Illustrative model observation; consult live evidence for current specifications."
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
id | string · uuid | Yes | Stable TensorTrace 3D asset UUID. |
title | string | Yes | Human-facing source object or package name; official source metadata takes precedence over UID filenames. |
description | string,null | No | Optional asset description. |
dataset_id | string | Yes | Case-preserved Hugging Face owner/repository identity. |
dataset_name | string | Yes | Dataset display name. |
publisher | string | Yes | Hugging Face namespace; not a verification of authorship. |
path | string | Yes | Logical root file within its dataset, excluding separate internal payload cards. |
format | string | Yes | Root file format. Values: usd, usda, usdc, usdz, glb, gltf |
byte_size | integer,null | Yes | Root file bytes; excludes separately referenced dependencies. Minimum: 0 |
source_thumbnail_url | string,null | Yes | Raw upstream image candidate at the pinned source revision. It has not necessarily passed worker validation; clients should display thumbnail_url instead. |
thumbnail_url | string,null · uri-reference | Yes | Local versioned /api/v1/openusd/assets/{id}/thumbnail?v=... endpoint for the validated normalized WebP. Null until media.status is ready; never a speculative upstream image URL. |
preview | object,null | Yes | A source-manifest or publisher-documented browser representation at the same immutable revision. The original source is preserved. |
media | object | Yes | Worker-owned source-image or generated-3D thumbnail status. Public page and image reads never acquire or render upstream content. |
raw_url | string | Yes | Immutable HF resolve URL for browser loading and download. |
source_url | string | Yes | Original HF source page. |
source_updated_at | string,null · date-time | Yes | Source file update if known, otherwise dataset modification time; not asset publication time. |
updated_scope | string | Yes | Whether the update timestamp describes the asset or its containing dataset. Values: asset, dataset |
revision | string | Yes | Immutable source commit SHA. |
license | string,null | Yes | Source license claim; not a grant by TensorTrace. |
license_url | string,null | No | Source license reference when available. |
sha256 | string,null | No | Observed root LFS SHA-256 when supplied. |
categories | array of string | Yes | Source dataset tags; not inferred physical object classes. |
metadata | object | Yes | Optional observed source package metadata. Consumers must tolerate additional fields. |
render | object,null | No | Worker scene validation, independent from poster availability. Null until this input is checked. Ready publisher thumbnails do not establish 3D compatibility. Interactive loading uses the same scene engine and geometry limits; worker source-download budgets are bounded separately. |
object_identity | object,null | No | Explicit source namespace, object ID and relationship evidence. Reconstruction methods retain separate logical assets. |
representations | array,null | No | Source-proven originals and their relationship basis; no implicit filename fusion. |
tags | array,null | No | Bounded source-owned object tags. |
author | object,null | No | Source-annotated original author; distinct from Hub publisher namespace. |
license_name | string,null | No | Readable source license identifier; no version is inferred when absent from source metadata. |
scene | object,null | No | Optional worker-measured animation count, bounded clip names/durations and skinned-mesh count for the current immutable input. |
group_id | string · uuid | No | Persistent logical identity; synthetic for proven duplicate packages. Existing source UUIDs remain source-specific. |
primary_source_id | string · uuid | No | |
canonical_url | string | No | |
source_count | integer | No | Minimum: 1 |
publishers | array of string | No | |
authors | array of object | No | Distinct explicitly supplied source author objects, never inferred from publisher names. |
sources | array of object | No | Max. items: 100 |
sources_offset | integer | No | Minimum: 0 |
sources_has_more | boolean | No | |
media_source_id | string,null · uuid | No | |
render_source_id | string,null · uuid | No | |
identity | object,null | No | Verified closed-package basis and safe closure summary. Filename/title/poster similarity is not identity evidence. |
Read a validated 3D asset thumbnail
GET /api/v1/openusd/assets/{id}/thumbnail
Serves an already prepared local WebP; never downloads or renders a source image during the request. Use the versioned thumbnail_url returned by the asset API. Only an active asset and a ready image at its current media version are served.
Access: public read; no TensorTrace API key.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
id | path | Yes | string · uuid | Stable TensorTrace 3D asset UUID. |
v | query | No | string | Current opaque media version from thumbnail_url. A matching version enables immutable caching; stale or unknown versions return 404. |
If-None-Match | header | No | string | Previously returned image ETag; a matching validator returns an empty 304 response. |
Request example
curl 'https://tensortrace.net/api/v1/openusd/assets/google/thumbnail'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Worker-validated normalized WebP image. | string · binary |
304 | Image ETag matches; no response body. | No declared JSON body |
404 | Asset or ready preview is unavailable, or v does not match the current media version. | No declared JSON body |
Response example · 200
The response contains original bytes or an image. Content types: image/webp. Preserve the declared encoding and checksum; do not parse it as JSON.
Read 3D dataset indexing coverage
GET /api/v1/openusd/datasets
Reads stored USD, GLB and glTF metadata without upstream acquisition. Public data only; source terms and preview fidelity vary by asset.
Access: public read; no TensorTrace API key.
Parameters
This operation has no path or query parameters.
Request example
curl 'https://tensortrace.net/api/v1/openusd/datasets'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Stored OpenUSD result. | object |
400 | Invalid query parameters. | No declared JSON body |
404 | Asset does not exist or is unavailable. | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"data": [
{
"id": "google/gemini-2.5-flash",
"name": "Google: Gemini 2.5 Flash",
"index_status": "example",
"indexed_at": "example"
}
]
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
data | array of object | Yes |
Download an original 3D asset file
GET /api/v1/openusd/assets/{id}/download
Explicitly streams the active asset’s stored, revision-pinned original file as an attachment. No caller URL, credentials, dependency packaging or GLB substitution. Public-IP/DNS pinning and per-hop Hugging Face HTTPS allowlisting guard the source request. Files with an indexed size above 512 MiB redirect to the pinned source with download=true. Proxy limits: 512 MiB, 120 seconds total and eight concurrent downloads. No buffering of the complete file or range/resume support. Size/deadline/network failures after headers abort the stream. Ordinary page and metadata reads never invoke this transfer.
Access: public read; no TensorTrace API key.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
id | path | Yes | string · uuid | Stable TensorTrace 3D asset UUID; the stored dataset, immutable revision and root path select the original file. |
representation | query | No | string Max. length: 4096 | Exact path from the stored representations list. The default remains the original primary file. Arbitrary URLs and unlisted paths are rejected. |
Request example
curl 'https://tensortrace.net/api/v1/openusd/assets/google/download'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Original file bytes, streamed unchanged. | string · binary |
307 | Known original is larger than the proxy budget; download directly from its pinned Hugging Face source. | No declared JSON body |
404 | Asset is unavailable or the upstream original no longer exists. | No declared JSON body |
413 | Upstream transfer exceeds the proxy budget despite its stored size. | No declared JSON body |
502 | Stored source identity is invalid or the source response cannot be served safely. | No declared JSON body |
503 | Concurrent download limit reached or upstream source temporarily unavailable. | No declared JSON body |
504 | Source deadline exceeded before response headers; later expiration aborts the transfer. | No declared JSON body |
Response example · 200
The response contains original bytes or an image. Content types: application/octet-stream. Preserve the declared encoding and checksum; do not parse it as JSON.
Page original public sources of a logical 3D asset
GET /api/v1/openusd/assets/{id}/sources
Same active-member source list used by SSR and Web. Source UUIDs retain their original metadata/download semantics. Inactive/gated sources are absent.
Access: public read; no TensorTrace API key.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
id | path | Yes | string · uuid | An active original source UUID or stable logical group UUID. |
offset | query | No | integer Default: 0; Minimum: 0; Maximum: 1000000 | Skip this many active public source aliases, ordered by original UUID. |
limit | query | No | integer Default: 100; Minimum: 1; Maximum: 100 | Maximum source aliases returned in this bounded page. |
Request example
curl 'https://tensortrace.net/api/v1/openusd/assets/google/sources?limit=1'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Bounded source page | object |
400 | Invalid source page parameters | No declared JSON body |
404 | No active source or logical asset | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"dataset_id": "example",
"publisher": "example",
"author": {}
}
],
"total_count": 1,
"offset": 0,
"limit": 1
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
data | array of object | Yes | |
total_count | integer | Yes | |
offset | integer | Yes | |
limit | integer | Yes |