SimReady Asset Composer

SimReady Asset Composer is the planning and generation layer before conversion. Give it the object you need, the robotic task it must support, and optionally one reference image or four ordered views. It composes those inputs into a simulation brief, chooses a rigid or articulated structure and recommends Build or Generate, creates the prototype, and can submit that prototype to SimReady automatically.

The workflow is input-agnostic: text-only, text plus one image, and text plus four views use the same endpoint and return the same composition resource. The API route is non-interactive and never pauses for clarification; the Rigyd web app uses the same composer concepts with an interactive review flow.

Prototype generation is charged separately from conversion. Completed composition prototypes use authored_to_simready. Uploaded 3D models use glb_to_simready. Query pricing for current costs.

Set auto_submit: true for an unattended Composition → SimReady run. Leave it false to inspect the generated prototype before submitting it.

Tip

Prefer a terminal command? rigyd compose "object description" --task "robotic task" --asset-class auto creates, polls, submits, and downloads the workflow. Add --review to stop at ready. See CLI & Python SDK.

Request

curl -X POST https://api.rigyd.com/api/compositions/generate \
  -H "Authorization: Bearer rgyd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A stainless steel cabinet with two hinged doors",
    "robot_task": "Open and close either door with a parallel gripper",
    "asset_class": "articulated",
    "generation_method": "auto",
    "geometry_builder": "codex",
    "auto_submit": true,
    "physical_context": {
      "dimensions_m": { "length": 0.8, "width": 0.45, "height": 1.2 },
      "mass_kg": 32,
      "materials": ["stainless steel"],
      "fixed_base": true
    }
  }'

JSON and multipart requests are supported. For multipart requests, attach images with repeated images[] fields. Image count must be 0, 1, or 4; four views are ordered front, right, back, left.

Field	Required	Rules
prompt	yes	1–2,000 characters
robot_task	yes	1–2,000 characters
asset_class	no	auto, rigid, or articulated; default auto
generation_method	no	auto (default), procedural (Build), or generative (Generate)
geometry_builder	no	Build engine: responses or codex (High quality); default codex
auto_submit	no	Boolean; default false
negative_prompt	no	Up to 255 characters
physical_context	no	dimensions_m, mass_kg, materials, and fixed_base
images	no	0, 1, or 4 JPEG, PNG, or WebP files; 10 MB each

robot_task shapes planning and routing (Build or Generate, rigid or articulated) for this one asset. When you create several assets for one scene, give each the part of the task that involves it, such as “push the IV pole beside the bed” for the pole and “open the top drawer” for the nightstand. Sending a whole-scene task to every asset can steer routing toward parts that belong to other objects.

An explicit rigid or articulated class overrides inference. auto requests classified as deformable or mixed fail before a prototype charge is taken.

generation_method is independent of simulation class. In Auto, the Physics Agent weighs form, craft and surface character against precise construction and technical relationships. Generate uses Tripo for suitable rigid assets whose organic or crafted form is decisive. Human manufacture, cavities, cutouts and thin walls do not automatically force Build; interior preservation risks are recorded as limitations. Working articulation, required separate components, fit-critical interfaces and controlled feature dimensions require Build. Missing or uncertain recommendations default to Build. A stated overall size alone does not force Build.

Generate does not support working articulation in this integration. Starting a prototype through POST /api/compositions/:id/submit with generative and an articulated brief returns 422 before charging. On this automatic /generate endpoint, a failure after planning is currently wrapped as 502 with the failed composition in data; read data.workflow.error for the cause. Both methods produce a prototype for review and later SimReady conversion. Neither method guarantees exact fit or manufacturing tolerances.

geometry_builder selects the engine within Build; it does not force Build in Auto or affect Generate pricing. responses uses the existing single Responses API build. codex runs the articulated Three.js skill in an isolated Codex worker, verifies the Physiq contract, visually reviews closed and articulated poses with Playwright, and exports the GLB from that same worker. Send geometry_builder: "responses" to use the standard builder. The web app defaults to Auto and places method overrides inside Physics brief details. Its High quality switch applies only to Build and starts enabled.

Choose codex when appearance or working articulation matters, such as a mechanism the robot must operate. It costs more (see the _codex keys in pricing) and takes longer. responses suits placeholders, background props and fast iteration.

Generate prototypes report their charge as rigid_prototype.credits_charged on the composition. Build prototypes do not report a charge on the composition; the applicable pricing key is the expected charge, and your credit history at app.rigyd.com/billing shows the actual one. Conversion and simulation jobs report credits_charged on the job.

When the 3D preview is ready, Rigyd emails the asset owner a link to inspect it. This notification is separate from final SimReady conversion completion.

Note

This endpoint does not require an Idempotency-Key. Overlapping identical requests for the same customer coalesce while the first request starts generation. A later identical batch job remains valid.

Response and polling

The endpoint returns 202 Accepted. Poll GET /api/compositions/:id:

{
  "data": {
    "id": "composition-id",
    "interaction_mode": "non_interactive",
    "requested_asset_class": "articulated",
    "geometry_builder": "codex",
    "generation_method": "auto",
    "generation": {
      "requested_method": "auto",
      "recommended_method": "procedural",
      "resolved_method": "procedural",
      "reason": "The cabinet needs separate doors and working hinges.",
      "requirements": ["moving_parts"],
      "confidence": "high",
      "limitations": [],
      "capability_version": "2026-10-26-h3-v2"
    },
    "physical_context": {
      "dimensions_m": { "length": 0.8, "width": 0.45, "height": 1.2 },
      "mass_kg": 32,
      "materials": ["stainless steel"],
      "fixed_base": true
    },
    "workflow": {
      "status": "running",
      "stage": "prototype_generation",
      "progress": 45,
      "auto_submit": true,
      "assumptions": [],
      "error": null
    },
    "conversion_job_id": null
  }
}

asset_brief.generation_plan exposes the Physics Agent’s recommendation, method confidence, decisive requirements, limitations and capability-guide version. generation records the requested, recommended and resolved methods for the actual attempt. Retries keep this snapshot; they do not silently switch providers when recommendations change.

Workflow statuses are running, ready, completed, failed, and cancelled. ready means the prototype is available and awaits manual SimReady submission. completed means automatic SimReady conversion completed.

Stages are composing, planning, prototype_generation, prototype_rendering, and simready_conversion. Poll every 3–5 seconds.

Composition IDs and conversion-job IDs are different. Poll the composition while it is planning or generating. Once submitted, conversion_job_id identifies the SimReady conversion used by the conversion-job endpoints.

Note

Articulated requests still run prototype_rendering when auto_submit=false. That stage exports the closed-pose GLB, articulation manifest, and four canonical captures used for review. It does not start SimReady conversion.

Create a prototype or change its method

For an existing interactive composition with a ready Physics brief, POST /api/compositions/:id/submit creates a paid prototype when none is ready. Its optional generation_method and geometry_builder fields control that start. Auto uses the current brief recommendation. A Build start returns a composition with geometry_alpha; a Generate start returns a composition with rigid_prototype. Poll the composition in either case.

PATCH /api/compositions/:id accepts generation_method to save an override before starting. An active attempt returns 409 for method changes. Explicitly changing the method after a completed or failed attempt opens a new paid attempt and clears its current prototype references; stored media is retained. A retry without this explicit change keeps its original method. The legacy POST /api/compositions/:id/geometry-alpha endpoint also honors Auto and explicit method choices for a first attempt. Existing Build attempts keep their method; it cannot switch an existing Generate attempt.

Revise Build geometry

POST /api/compositions/:id/geometry-alpha with { "feedback": "..." } (at most 2,000 characters) revises a ready Build prototype. The builder and asset class stay the same. A valid revision reuses the original prototype charge; a new attempt after a settled failure may charge again. Feedback without ready geometry, or ready geometry without feedback, returns 409. Generate prototypes cannot be revised.

The 202 response is the composition. Poll GET /api/compositions/:id/geometry-alpha until geometry_alpha.status is ready or failed. A revision does not start a SimReady conversion; submit the prototype when it is ready.

Submit a reviewed prototype

When auto_submit=false, wait for workflow status ready, then submit the stored prototype:

curl -X POST https://api.rigyd.com/api/compositions/composition-id/submit \
  -H "Authorization: Bearer rgyd_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

For a ready prototype, the JSON body may carry asset_license: the license of the source asset (for example CC-BY-4.0), up to 200 characters, default proprietary. It is written into the delivered USD’s SimReady metadata for both rigid and articulated prototypes and returned as report.simready_metadata.asset_license; the USD’s author is always Rigyd. A value that is not a string or exceeds 200 characters returns 400.

The conversion reads one UV set per material, because a MuJoCo material has one. A prototype whose GLB binds any texture map to a UV set other than the first (TEXCOORD_0) returns 422 before any credit is reserved, with the node, material and slot of each such map in detail and textures. Rebuild the prototype to fix it.

The endpoint returns 202 Accepted with the conversion job, not another composition envelope:

{
  "data": {
    "id": "conversion-id",
    "status": "queued",
    "progress": 0,
    "job_type": "authored_to_simready",
    "credits_charged": 0,
    "composition_id": "composition-id"
  }
}

Poll GET /api/conversions/:id for that returned ID. The original composition also exposes it as conversion_job_id and advances through simready_conversion to completed.

List compositions

GET /api/compositions?page=1&pageSize=25 lists your composition workflows newest first. These are not returned by GET /api/conversions; only the SimReady conversion created after submission appears in the conversion-job list.