Download result

Download the result of a completed SimReady conversion as a ZIP archive. Use the conversion-job ID from a direct 3D upload or from Asset Composer’s conversion_job_id; composition IDs do not work on this endpoint.

Method	GET
Path	/api/conversions/:id/result
Returns	application/zip; legacy jobs without stored packages may return JSON

Query parameters

Param	Values	Default	Notes
format	usd · mjcf · all	all	usd = USD + textures only. mjcf = MuJoCo XML package. all = both.

Examples

curl

curl -L "https://api.rigyd.com/api/conversions/abc123.../result?format=usd" \
  -H "Authorization: Bearer rgyd_live_..." \
  -o simready.zip

JavaScript

import fs from 'node:fs';
import { Readable } from 'node:stream';

const res = await fetch(
  `https://api.rigyd.com/api/conversions/${jobId}/result?format=usd`,
  { headers: { Authorization: `Bearer ${process.env.RIGYD_API_KEY}` } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await new Promise((resolve, reject) => {
  Readable.fromWeb(res.body)
    .pipe(fs.createWriteStream('simready.zip'))
    .on('finish', resolve).on('error', reject);
});

Python

import os, requests

with requests.get(
    f"https://api.rigyd.com/api/conversions/{job_id}/result",
    headers={"Authorization": f"Bearer {os.environ['RIGYD_API_KEY']}"},
    params={"format": "usd"},
    stream=True,
) as res:
    res.raise_for_status()
    with open("simready.zip", "wb") as out:
        for chunk in res.iter_content(chunk_size=1024 * 1024):
            out.write(chunk)

ZIP contents

<name> below is the asset name chosen by the pipeline: for compositions it is derived from the prompt, and for uploads it is not always your filename. List the archive to find the entry point instead of predicting it. <basename> is your uploaded filename without its extension.

format=usd

usd/<name>/<name>.usd            # entry point — open this one
usd/<name>/payloads/*.usd        # base, meshes, physics layers
usd/<name>/payloads/materials/OmniPBR/*.mdl  # when an MDL material is used
usd/<name>/textures/*.png
usd/<name>/.thumbs/256x256/<name>.usd.png   # SimReady thumbnail (hidden folder)

format=mjcf

mjcf/<name>.xml
mjcf/meshes/*.obj      # visual meshes, with UVs
mjcf/meshes/*.stl      # collision hulls
mjcf/textures/*.png

format=all

usd/<name>/<name>.usd            # entry point — open this one
usd/<name>/payloads/*.usd        # base, meshes, physics layers
usd/<name>/payloads/materials/OmniPBR/*.mdl  # when an MDL material is used
usd/<name>/textures/*.png
usd/<name>/.thumbs/256x256/<name>.usd.png   # SimReady thumbnail (hidden folder)
mjcf/<name>.xml
mjcf/meshes/*.obj
mjcf/meshes/*.stl
mjcf/textures/*.png

The USD is composed — open the entry point, keep the tree

usd/<name>/<name>.usd is a kind = "component" entry point that references payloads/<name>_base.usd and payloads payloads/<name>_physics.usd. Extracting that one file and loading it gives you an empty stage. Unzip the whole usd/<name>/ directory and point your loader at the entry point; the root layer is also the first entry in the archive, which is what three.js’s USDLoader reads.

Assets delivered before the composition change are still one flat file under usd/<basename>/, and archives already downloaded are not rewritten — so handle both shapes if you store them.

The thumbnail lives in a dot folder

Since SimReady 2026.08.0 the USD package carries a 256×256 thumbnail at usd/<name>/.thumbs/256x256/<name>.usd.png, the location the specification’s SR.002 asks for. Because the folder name starts with a dot, some unzip tools and file browsers hide it by default — it is there even if you do not see it. report.thumbnail.path gives the same path relative to the USD file. Assets converted before 2026.08.0 have no thumbnail.

The MJCF tree lost a folder level

The MuJoCo package used to nest everything one level deeper — mjcf/<name>/<name>.xml, mjcf/<name>/meshes/…. It is now flat under mjcf/, as shown above.

This came from a SimReady conformance fix upstream: NP.005 (asset-folder-structure) wants an asset root with exactly one intermediate folder, and the extra level made NVIDIA’s validator read the asset root as literally "mjcf" and then ask the filename to contain it.

If you address files by path inside the archive, check that code. Globbing for *.xml or *.stl anywhere under the root is unaffected. Already-downloaded archives are not rewritten, so if you store them you may need to handle both shapes.

Combining MJCF assets in one scene

Each MJCF file is a standalone test world for one asset, not a scene fragment. When you merge several into one MuJoCo scene:

• One floor. Every file includes <geom name="ground" type="plane"> in its worldbody. Keep one floor for the scene and drop the per-asset planes.
• Prefix names. Mesh, material, texture and geom names such as material_0, visual_0 and collision_0 repeat across assets, and each file has an unnamed top-level <default> geom class with that asset’s friction. Prefix each asset’s names and references, or use MuJoCo <attach> (mjSpec attach) with a prefix; plain <include> does not prefix. Move each asset’s defaults into a named class so they apply only to its geoms.
• Set the floor’s friction. MuJoCo combines two contacting geoms by taking the larger friction value (unless their priority differs). A floor at the default friction of 1.0 overrides lower friction tuned on an asset. Give the floor the surface friction you intend, or give asset geoms a higher priority.
• Wheels and casters are solid. Only joints authored for an articulated Build asset move. On rigid and Generate assets, casters are part of the body, so a pushed cart slides on contact friction and can tip. fixed_base: false makes a free body, not a rolling one. If rolling matters, request an articulated asset and name the wheels as continuous joints.
• Check which way it faces. No explicit front direction is delivered. Build geometry is authored facing +Z in Y-up, which becomes −Y in the delivered Z-up files. Generate and uploaded assets have no facing convention. Confirm with the prototype captures, joint axes (drawer slide direction, hinge side) or a render before placing instances.

Errors specific to this endpoint

Status	Body	When
400	{ "error": "Invalid format. Expected one of: usd, mjcf, all" }	Bad format value
404	{ "error": "Conversion job not found" }	Bad id or not your job
404	{ "error": "MJCF package is not available for this conversion" }	format=mjcf but the pipeline did not produce an MJCF package
409	{ "error": "Job not yet completed", "status": "running" }	Job is still in flight
502	upstream fetch failure	Underlying media store unreachable

Tip

The API returns the ZIP directly and requires authentication. Legacy jobs without stored output packages can instead return { "data": { "url": "..." } }. Check the response Content-Type before saving it: follow data.url for that JSON fallback and keep your Rigyd bearer token on Rigyd API requests only. Re-call this endpoint when a temporary result URL expires.