Job lifecycle

View Markdown llms-full.txt

Every conversion follows the same lifecycle, regardless of whether you submitted a 3D file, image, text prompt, or simulation request.

Status flow

submitting ──► preprocessing ──► queued ──► running ──► completed
                                                    └─► failed

Status	Meaning
`submitting`	Initial state — credit reserved, file being staged. Usually invisible to clients.
`preprocessing`	Non-GLB input is being converted to a clean GLB on the makina-worker.
`queued`	Submitted to the SimReady pipeline, waiting for a runner.
`running`	Pipeline is actively processing (export → align → physics → collision → USD).
`completed`	Done. `output.model.url` is ready. Credit was charged.
`failed`	Something went wrong. `error` is populated. Credit is auto-refunded.

GLB inputs skip the preprocessing state and go straight to queued.

What does and does not reach `failed`

A SimReady conformance failure does not fail the job. A non-conformant asset is still delivered, status is completed, and the credit is charged — the verdict rides along in report.validation, which is where you check it. See SimReady Validation.

What reaches failed is a correctness problem — a statement about our own output rather than about the specification:

the USD and the MJCF disagree about the asset they describe
an internal invariant is violated
an export is missing or unwritable
an input manifest does not match the mesh it describes

Plus the ordinary infrastructure cases: a malformed upload, an unreachable upstream, a pipeline crash.

Progress and stage

progress is 0-100. stage is a free-form string identifying the current pipeline step (e.g. "export", "physics", "collision_decompose"). Don’t pattern-match on stage — treat it as a hint for human-readable progress UI.

Preprocessing component

When the input is non-GLB, the response includes a preprocess block:

{
  "preprocess": {
    "status": "completed",
    "steps": ["export", "align", "transform", "compress", "process"],
    "started_at": "2026-05-06T12:00:05.000Z",
    "completed_at": "2026-05-06T12:00:42.000Z",
    "error": null,
    "input_stats": { "vertex_count": 12345, "face_count": 6789, "...": "..." },
    "telemetry": { "duration_ms": 37123, "...": "..." },
    "intermediate_glb": {
      "url": "https://assets.rigyd.com/.../intermediate.glb",
      "name": "intermediate.glb"
    }
  }
}

preprocess.status enum: skipped · pending · running · completed · failed. For GLB inputs status === "skipped" and the rest of the block is null.

Full payload shape

{
  "data": {
    "id": "abc123...",
    "physiq_job_id": "phy_...",
    "status": "completed",
    "filename": "toolbox.glb",
    "file_size_bytes": 1245678,
    "stage": "export",
    "progress": 100,
    "error": null,
    "timing": {
      "queued_at": "...",
      "started_at": "...",
      "completed_at": "..."
    },
    "parameters": {
      // Echo of fields you sent (target_triangle_count, prompt, etc.)
    },
    "report": {
      // pipeline.*    — mass, friction, inertia, collision, timing
      // validation.*  — SimReady conformance. Badge `validation.profiles_passing`;
      //                 `validation.spec_release` names the spec release scored against
      // invariants.*  — our own correctness checks; `ok` is always true on a delivered asset
    },
    "job_type": "glb_to_simready",
    "credits_charged": 1,
    "input": {
      "model": { "url": "...", "name": "toolbox.glb" },         // 3D submissions
      "images": [{ "url": "...", "name": "front.jpg" }],         // Generate (images)
      "metadata": null                                            // Set for ZIP uploads
    },
    "preprocess": { /* see above */ },
    "output": {
      "model":        { "url": "...", "name": "toolbox.usd", "size": 982341 },
      "textures":     [{ "url": "...", "name": "diffuse.png" }],
      "mjcf_package": { "url": "...", "name": "toolbox-mjcf.zip", "size": 1234 },
      "sim_video":    null,  // populated on simulate_usd jobs
      "sim_gif":      null,
      "sim_log":      null
    },
    "source_job":  null,    // populated on simulate_usd jobs (points back at the parent)
    "simulations": [],      // simulations[] of this job (children)
    "createdAt":   "2026-05-06T12:00:00.000Z",
    "updatedAt":   "2026-05-06T12:01:32.000Z"
  }
}

Refund guarantees

A failed job is refunded once — Rigyd uses an internal refund_applied_at guard so retries don’t double-refund. You don’t need to track this client-side. Just check credits_charged on the final job payload.