3D → SimReady

Upload a 3D model and Rigyd returns a SimReady USD asset — physics properties, collision meshes, and materials filled in automatically.

Method	POST
Path	/api/conversions
Content-type	multipart/form-data
Job type	glb_to_simready
Credits	Query glb_to_simready in pricing

Accepted formats

.glb, .gltf, .fbx, .obj, .stl, .ply, .usd, .usda, .usdc, .usdz, and .zip (for multi-file inputs). The file must contain a mesh: a .ply point cloud or Gaussian splat has no faces and is refused with 400 before it is charged. See Point clouds and Gaussian splats.

.glb skips the preprocessing stage and is the fastest path unless you enable mesh optimization. Anything else goes through Blender-based cleanup first — see Supported formats for the rules around ZIP archives, OBJ + MTL, GLTF + bin, and USD with references.

Request fields

Field	Type	Required	Notes
file	file (upload)	yes	The 3D model. See accepted formats above.
description	string	no	What the object is, in your words. Explicit material, size and mass claims in it outrank what the pipeline reads off the renders. Max 2000 characters.
declared	JSON object	no	What you already KNOW: mass_kg, volume_m3, dimensions_m (length_m/width_m/height_m, any subset), materials (strings), object_category, construction and wall_mm. Outranks both the description and the renders.
asset_license	string	no	The license of the source asset you upload, e.g. CC-BY-4.0. Written into the delivered USD’s SimReady metadata and returned as report.simready_metadata.asset_license. Max 200 characters; trimmed, blank means unset. Default proprietary. See Asset license.
optimize	boolean	no	Run mesh optimization during preprocessing. Default false.
target_triangle_count	int	when optimize=true	Target triangle count for optimization. 1000–1000000.
threshold	float	no	CoACD collision-decomposition concavity threshold (advanced).
llm_provider	string	no	Override the LLM used for material identification (advanced).
skip_validation	boolean	no	Suppresses the internal correctness gate. Does not skip SimReady scoring. Leave unset. Default false.

Asset license

You own what you upload, so its license is yours to state. asset_license records the license of the source asset, not of Rigyd’s conversion; the USD’s author field is always Rigyd. When you send nothing, the asset is stamped proprietary. A value that is not a string or is longer than 200 characters returns 400 before the job is created or charged.

Size, mass and materials

Your file’s coordinates are taken as metres, which is what glTF requires, and a file that is plausibly metric keeps its own size. To decide, the pipeline estimates the object’s real size from its renders without being shown the file’s dimensions, then compares:

• Within a factor of two of the estimate: the delivered asset keeps the size you uploaded, and geometry.dimensions_source is mesh.
• Further off: the asset is rescaled to the estimate, and dimensions_source is estimated. This catches files exported in millimetres or centimetres, and files normalised to a 1 m box, as many generators and asset stores ship them — a tennis ball normalised to 0.26 m is delivered at 0.067 m.

The estimate is blind on purpose: shown the file’s box, a model tends to repeat it, and a normalised file would pass as metric. declared dimensions outrank both, and dimensions_source is then declared.

description and declared say what the file cannot. Use declared whenever you have the numbers: it is read as numbers, while a description is prose and prose has to be interpreted. A declared box is applied per axis, so the delivered asset measures exactly what you stated.

-F 'declared={"mass_kg": 0.411, "dimensions_m": {"length_m": 0.21, "width_m": 0.158, "height_m": 0.06}}'

A partial declaration is fine — state the one axis you measured.

What the object is made of, and what it is

A render shows shape, colour and finish. It cannot show what a thing is made of when the object imitates another material, and that is where the largest mass errors come from: a plastic lemon looks exactly like a lemon, a foam brick like a fired one. Two fields say what the pictures cannot.

materials is what it is made of. It replaces what the pipeline reads off the renders, so state all of them if the object is genuinely mixed.

construction is how that material is arranged — "shell" (a wall around empty space) or "solid" (a filled region) — with an optional wall_mm. This matters more than it looks: naming the plastic in a replica lemon without saying it is hollow makes it heavier, because plastic is denser than fruit peel.

object_category is the interior model, one of:

hollow_thin, hollow_thick, upholstered, padded, stuffed, solid, solid_wood, composite_frame, electronic, wearable, packaged_dry, packaged_wet

Sealed retail packaging converts as the product as sold — a cracker box is its crackers, a soup can its soup. It is also how fill state is stated: an empty box is hollow_thin, a full one packaged_dry (or packaged_wet for a can, jar or bottle).

-F 'declared={"materials": ["hard plastic"], "construction": "shell", "wall_mm": 1.5, "object_category": "hollow_thin"}'

Where each number came from

The job report labels the provenance of every physical fact it returns: mass.source, geometry.dimensions_source, materials_source and asset.category_source. declared is what you stated, mesh is measured off your uploaded geometry, and recalled, identified and estimated are the pipeline’s own inference. Anything you declare comes back labelled declared.

Examples

curl

curl -X POST https://api.rigyd.com/api/conversions \
  -H "Authorization: Bearer rgyd_live_..." \
  -F "file=@./toolbox.glb" \
  -F "description=A steel hand-tool box, empty" \
  -F 'declared={"mass_kg": 2.4, "dimensions_m": {"length_m": 0.48}}' \
  -F "asset_license=CC-BY-4.0" \
  -F "optimize=true" \
  -F "target_triangle_count=50000"

JavaScript

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./toolbox.glb')]), 'toolbox.glb');
form.append('description', 'A steel hand-tool box, empty');
form.append('declared', JSON.stringify({ mass_kg: 2.4, dimensions_m: { length_m: 0.48 } }));
form.append('optimize', 'true');
form.append('target_triangle_count', '50000');

const res = await fetch('https://api.rigyd.com/api/conversions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RIGYD_API_KEY}` },
  body: form,
});
const { data } = await res.json();

Python

import json, os, requests

with open("toolbox.glb", "rb") as f:
    res = requests.post(
        "https://api.rigyd.com/api/conversions",
        headers={"Authorization": f"Bearer {os.environ['RIGYD_API_KEY']}"},
        files={"file": ("toolbox.glb", f, "model/gltf-binary")},
        data={
            "description": "A steel hand-tool box, empty",
            "declared": json.dumps({"mass_kg": 2.4, "dimensions_m": {"length_m": 0.48}}),
            "optimize": "true",
            "target_triangle_count": 50000,
        },
    )
job = res.json()["data"]

Response — 202 Accepted

{
  "data": {
    "id": "abc123...",
    "physiq_job_id": "phy_...",
    "status": "queued",
    "filename": "toolbox.glb",
    "progress": 0,
    "job_type": "glb_to_simready",
    "credits_charged": 5,
    "createdAt": "2026-05-06T12:00:00.000Z"
  }
}

For non-GLB inputs, status starts at preprocessing while the model is converted to a clean GLB, then transitions to queued → running → completed.

Tip

Uploaded models use glb_to_simready; completed composition prototypes use authored_to_simready. Each has its own credit cost. Query GET /api/conversions/pricing instead of hard-coding prices in a client.

Next: poll the job → download the USD.